Übersicht
Mit der Lookup API können Client-Anwendungen Anfragen an die Safe Browsing- um zu prüfen, ob URLs auf einer Safe Browsing-Liste stehen. Wird eine URL auf einem oder werden die übereinstimmenden Informationen zurückgegeben.
URLs prüfen
Wenn du prüfen möchtest, ob eine URL auf einer Safe Browsing-Liste steht, sende eine HTTP-POST-Anfrage an den
threatMatches.find
:
- Die HTTP-
POST-Anfrage kann bis zu 500 URLs enthalten. Die URLs müssen gültig sein (siehe RFC 2396) Sie müssen jedoch nicht kanonisiert oder codiert werden. - In der HTTP-
POST-Antwort werden die übereinstimmenden URLs zusammen mit der Cache-Dauer zurückgegeben.
Beispiel: ThreatMatches.find
HTTP-POST-Anfrage
Im folgenden Beispiel werden zwei Safe Browsing-Listen und drei URLs an den Server gesendet, ob es eine Übereinstimmung gibt.
Anfrageheader
Der Anfrageheader enthält die Anfrage-URL und den Inhaltstyp. Denken Sie daran,
Ihren API-Schlüssel für API_KEY in der URL.
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) sowie Informationen zur Bedrohung (Listennamen und URLs). Weitere Informationen finden Sie in der threatMatches.find-Anfragetext und die Erklärungen nach dem 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, keine
einzelner Nutzer. (Client-Informationen werden für das serverseitige Logging und Accounting verwendet. Zur Auswahl stehen
einen beliebigen Namen für die Client-ID. Wir empfehlen jedoch, einen Namen zu wählen, der die tatsächliche Identität der
(z. B. der Name Ihres Unternehmens, dargestellt als ein Wort und in Kleinbuchstaben).
Safe Browsing-Listen
Die Felder threatType, platformType und threatEntryType
zur Identifizierung (Name) von Safe Browsing-Listen kombiniert. In diesem Beispiel werden zwei Listen identifiziert:
MALWARE/WINDOWS/URL und SOCIAL_ENGINEERING/WINDOWS/URL. Prüfen Sie vor dem Senden einer Anfrage, ob der Typ der
von Ihnen angegebene Kombinationen sind gültig (siehe Safe Browsing-Listen).
Bedrohungs-URLs
In diesem 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:Für die Lookup API und die Methode threatMatches sollte immer das Feld URL verwendet werden.
und niemals das Feld hash (siehe ThreatEntry).
HTTP POST-Antwort
Im folgenden Beispiel gibt die Antwort eine Übereinstimmung zurück: der beiden im Feld die sich auf einer der beiden Safe Browsing-Listen befinden, 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 URLs auf diese Listen, die Metadaten (falls verfügbar) und die Cache-Dauer). Weitere Informationen finden Sie in der threatMatches.find Antworttext und die Erklärungen nach dem Codebeispiel.
Hinweis:Wenn es keine Übereinstimmungen gibt (wenn also keine der angegebenen URLs angegeben wurde)
in der Anfrage auf einer der in der Anfrage angegebenen Listen gefunden werden), wird die HTTP-Antwort POST
gibt 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 enthält die Namen der Safe Browsing-Listen und die URLs (falls
es gibt eine Übereinstimmung. In diesem Beispiel wurden zwei URLs (urltocheck1.org und urltocheck2.org) auf einer der folgenden Seiten gefunden:
die Safe Browsing-Listen (MALWARE/WINDOWS/URL) auf, sodass die übereinstimmenden Informationen zurückgegeben werden. Die dritte URL
(urltocheck3.org) wurde auf keiner der Listen gefunden. Für diese URL werden daher keine Informationen zurückgegeben.
Metadaten
Das Feld threatEntryMetadata ist optional und enthält zusätzliche Informationen zu
den Abgleich mit den Bedrohungen. Derzeit sind Metadaten für die Safe Browsing-Liste für MALWARE/WINDOWS/URL verfügbar.
(siehe Metadaten).
Cache-Dauer
Das Feld „cacheDuration“ gibt an, wie lange die URL als unsicher gelten muss
(siehe Caching).