Überblick
Mit der Lookup API können Ihre Clientanwendungen Anfragen an die Safe Browsing-Server senden, um zu prüfen, ob sich URLs auf einer Safe Browsing-Liste befinden. Wenn eine URL in einer oder mehreren Listen gefunden wird, werden die übereinstimmenden Informationen zurückgegeben.
URLs prüfen
Wenn Sie prüfen möchten, ob sich eine URL auf einer Safe Browsing-Liste befindet, senden Sie eine HTTP-POST
-Anfrage an die Methode threatMatches.find:
- Die HTTP-
POST
-Anfrage kann bis zu 500 URLs enthalten. Die URLs müssen gültig sein (siehe RFC 2396), aber sie müssen nicht kanonisiert oder codiert sein. - Die HTTP-Antwort
POST
gibt die übereinstimmenden URLs zusammen mit der Cache-Dauer zurück.
Beispiel: threatMatches.find
HTTP POST-Anfrage
Im folgenden Beispiel werden zwei Safe Browsing-Listen und drei URLs an den Server gesendet, um festzustellen, ob es eine Übereinstimmung gibt.
Anfrageheader
Der Anfrageheader enthält die Anfrage-URL und den Inhaltstyp. Denken Sie daran, in der URL Ihren API-Schlüssel durch API_KEY
zu ersetzen.
POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Anfragetext
Der Anfragetext enthält die Clientinformationen (ID und Version) und die Bedrohungsinformationen (Listennamen und URLs). Weitere Informationen finden Sie im Anfragetext von threatMatches.find und in den Erläuterungen zu diesem Codebeispiel.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "threatInfo": { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "platformTypes": ["WINDOWS"], "threatEntryTypes": ["URL"], "threatEntries": [ {"url": "http://www.urltocheck1.org/"}, {"url": "http://www.urltocheck2.org/"}, {"url": "http://www.urltocheck3.com/"} ] } }
Kundeninformationen
Die Felder clientID
und clientVersion
sollten eine Clientimplementierung eindeutig identifizieren, nicht einen einzelnen Nutzer. (Client-Informationen werden für die serverseitige Protokollierung und Abrechnung verwendet. Sie können einen beliebigen Namen für die Client-ID wählen. Wir empfehlen jedoch einen Namen, der die wahre Identität des Clients darstellt, z. B. den Namen Ihres Unternehmens, der aus einem Wort besteht und nur Kleinbuchstaben enthält.
Safe Browsing-Listen
Die Felder threatType
, platformType
und threatEntryType
werden kombiniert, um Safe Browsing-Listen zu identifizieren (Name). Im Beispiel werden zwei Listen identifiziert: MALWARE/WINDOWS/URL und SOCIAL_ENGINEERING/WINDOWS/URL. Prüfen Sie vor dem Senden einer Anfrage, ob die angegebenen Typkombinationen gültig sind (siehe Safe Browsing-Listen).
Bedrohungs-URLs
Im Beispiel enthält das Array threatEntries
drei URLs (urltocheck1.org, urltocheck2.org und urltocheck3.org), die mit den beiden Safe Browsing-Listen abgeglichen werden.
Hinweis:Die Lookup API und die Methode threatMatches
sollten immer das Feld URL
und nicht das Feld hash
verwenden (siehe ThreatEntry).
HTTP POST-Antwort
Im folgenden Beispiel gibt die Antwort eine Übereinstimmung zurück. Zwei der drei in der Anfrage angegebenen URLs befinden sich in einer der beiden Safe Browsing-Listen, die in der Anfrage angegeben sind.
Antwortheader
Der Antwortheader enthält den HTTP-Statuscode und den Inhaltstyp.
HTTP/1.1 200 OK Content-Type: application/json
Antworttext
Der Antworttext enthält die Übereinstimmungsinformationen (die Listennamen und die in diesen Listen gefundenen URLs, die Metadaten, falls verfügbar, und die Cache-Dauer). Weitere Informationen finden Sie im Antworttext vonthreatMatches.find und in den Erläuterungen zu diesem Codebeispiel.
Hinweis:Wenn keine Übereinstimmungen vorhanden sind, also keine der in der Anfrage angegebenen URLs in einer der in einer Anfrage angegebenen Listen gefunden werden, gibt die HTTP-POST
-Antwort einfach ein leeres Objekt im Antworttext zurück.
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": {"url": "http://www.urltocheck1.org/"}, "threatEntryMetadata": { "entries": [{ "key": "malware_threat_type", "value": "landing" }] }, "cacheDuration": "300.000s" }, { "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": {"url": "http://www.urltocheck2.org/"}, "threatEntryMetadata": { "entries": [{ "key": "malware_threat_type", "value": "landing" }] }, "cacheDuration": "300.000s" }] }
Übereinstimmungen
Das matches
-Objekt listet die Namen der Safe Browsing-Listen und die URLs auf, sofern sie übereinstimmen. Im Beispiel wurden zwei URLs (urltocheck1.org und urltocheck2.org) in einer der Safe Browsing-Listen (MALWARE/WINDOWS/URL) gefunden, sodass die übereinstimmenden Informationen zurückgegeben werden. Die dritte URL (urltocheck3.org) wurde in keiner der beiden Listen gefunden, sodass für diese URL keine Informationen zurückgegeben werden.
Metadaten
Das Feld threatEntryMetadata
ist optional und enthält zusätzliche Informationen zur Bedrohungsübereinstimmung. Derzeit sind Metadaten für die Safe Browsing-Liste MALWARE/WINDOWS/URL verfügbar (siehe Metadaten).
Cache-Dauer
Das Feld cacheDuration
gibt an, wie lange die URL als unsicher eingestuft werden muss (siehe Caching).