Safe Browsing Lookup API (Version 4)

Ü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).