Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

Update API verwenden

Überblick

Mit der Update API können Ihre Clientanwendungen verschlüsselte Versionen der Web-Risiko-Listen herunterladen, um sie in einer lokalen Datenbank oder einer speicherinternen Datenbank zu speichern. URLs können dann lokal überprüft werden. Wenn eine Übereinstimmung in der lokalen Datenbank gefunden wird, sendet der Client eine Anfrage an die Web Risk-Server, um zu überprüfen, ob die URL in den Web Risk-Listen enthalten ist.

Lokale Datenbank aktualisieren

Um immer auf dem neuesten Stand zu bleiben, müssen Kunden die Web Risk-Listen in ihrer lokalen Datenbank regelmäßig aktualisieren. Um Bandbreite zu sparen, laden Kunden die Hash-Präfixe der URLs und nicht die URLs selbst herunter. Wenn z. B. "www.badurl.com/" auf einer Web Risk-Liste steht, laden Kunden den SHA256-Hash-Präfix dieser URL und nicht die URL selbst herunter. In den meisten Fällen sind die Hash-Präfixe 4 Byte lang, was bedeutet, dass die durchschnittlichen Bandbreitenkosten für das Herunterladen eines einzelnen Listeneintrags vor der Komprimierung 4 Byte betragen.

Senden Sie zum Aktualisieren der Web Risk-Listen in der lokalen Datenbank eine HTTP-GET-Anfrage an die Methode threatLists.computeDiff:

  • Die HTTP-GET-Anfrage enthält den Namen der zu aktualisierenden Liste sowie Clienteinschränkungen zur Berücksichtigung von Speicher- und Bandbreitenbeschränkungen.
  • Die HTTP-GET-Anfrage gibt entweder eine vollständige Aktualisierung oder eine teilweise Aktualisierung zurück. Die Antwort könnte auch eine empfohlene Wartezeit bis zum nächsten Compute-Diff-Vorgang zurückgeben.

Beispiel: threatLists.computeDiff

HTTP-GET-Anfrage

Im folgenden Beispiel werden die Diffs für die MALWARE Web Risk-Liste angefordert. Weitere Informationen finden Sie in den threatLists.computeDiff-Abfrageparametern und in den Erläuterungen nach dem Codebeispiel.

HTTP-Methode und URL:

GET "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"

PowerShell

Führen Sie folgenden Befehl aus:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri ""https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"" | Select-Object -Expand Content

Sie sollten in etwa folgende JSON-Antwort erhalten:

{
  "recommendedNextDiff": "2020-01-08T19:41:45.436722194Z",
  "responseType": "RESET",
  "additions": {
    "rawHashes": [
      {
        "prefixSize": 4,
        "rawHashes": "AArQMQAMoUgAPn8lAE..."
      }
    ]
  },
  "newVersionToken": "ChAIARAGGAEiAzAwMSiAEDABEPDyBhoCGAlTcIVL",
  "checksum": {
    "sha256": "wy6jh0+MAg/V/+VdErFhZIpOW+L8ulrVwhlV61XkROI="
  }
}

Web Risk-Listen

Das Feld threatType gibt die Web Risk-Liste an. In diesem Beispiel werden die Diffs für die MALWARE Web Risk-Liste angefordert.

Versionstoken

Das Feld versionToken enthält den aktuellen Clientstatus der Web Risk-Liste. Versionstokens werden im Feld newVersionToken der Antwort threatLists.computeDiff zurückgegeben. Lassen Sie bei ersten Aktualisierungen das Feld versionToken leer.

Größenbeschränkungen

Das Feld maxDiffEntries gibt die Gesamtzahl der Aktualisierungen an, die der Client verwalten kann (im Beispiel 2.048). Das Feld maxDatabaseEntries gibt die Gesamtzahl der Einträge an, die die lokale Datenbank verwalten kann (im Beispiel 4.096). Clients sollten Größenbeschränkungen nur dann festlegen, wenn Speicher- oder Bandbreitenbeschränkungen gelten. Weitere Informationen finden Sie unter Einschränkungen aktualisieren.

Unterstützte Komprimierungen

Im Feld supportedCompressions sind die vom Client unterstützten Komprimierungstypen aufgeführt. In diesem Beispiel unterstützt der Client nur unkomprimierte Rohdaten. Web Risk unterstützt jedoch zusätzliche Komprimierungstypen. Weitere Informationen finden Sie unter Komprimierung.

HTTP-GET-Antwort

In diesem Beispiel gibt die Antwort eine Teilaktualisierung für die Liste "Web Risk" mit dem angeforderten Komprimierungstyp zurück.

Antworttext

Der Antworttext enthält die Diffs-Informationen (den Antworttyp, die auf die lokale Datenbank anzuwendenden Hinzufügungen und Entfernungen, das neue Versions-Token und eine Prüfsumme).

In diesem Beispiel enthält die Antwort auch eine empfohlene nächste Diff-Zeit. Weitere Informationen finden Sie im Antworttext threatLists.computeDiff und in den Erläuterungen nach dem Codebeispiel.

{
  "responseType" :   "DIFF",
  "recommendedNextDiff": "2019-12-31T23:59:59.000000000Z",
  "additions": {
    "compressionType": "RAW",
    "rawHashes": [{
      "prefixSize": 4,
      "rawHashes":  "rnGLoQ=="
    }]
  },
  "removals": {
    "rawIndices": {
      "indices": [0, 2, 4]
    }
  },
  "newVersionToken": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
  "checksum": {
    "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
  },
  "recommendedNextDiff": "2019-07-17T15:01:23.045123456Z"
}

Datenbank-Diffs

Das Feld responseType gibt eine teilweise Aktualisierung (DIFF) oder eine vollständige Aktualisierung (RESET) an. Im Beispiel werden partielle Diffs zurückgegeben, sodass die Antwort sowohl Hinzufügungen als auch Entfernungen enthält. Es kann mehrere Sätze von Hinzufügungen geben, aber nur einen Satz von Entfernungen. Weitere Informationen finden Sie unter Datenbank-Diffs.

Neues Versionstoken

Das Feld newVersionToken enthält das neue Versionstoken für die neu aktualisierte Web Risk-Liste. Clients müssen den Status des neuen Clients für nachfolgende Aktualisierungsanfragen speichern (das Feld versionToken in der threatLists.computeDiff-Anfrage).

Prüfsummen

Mit der Prüfsumme können Clients prüfen, ob die lokale Datenbank beschädigt ist. Wenn die Prüfsumme nicht übereinstimmt, muss der Client die Datenbank löschen und eine Aktualisierung mit einem leeren versionToken-Feld noch einmal ausführen. Clients in dieser Situation müssen jedoch die Zeitintervalle für Aktualisierungen einhalten. Weitere Informationen finden Sie unter Anfragehäufigkeit.

Das Feld recommendedNextDiff gibt einen Zeitstempel an, bis zu dem der Client warten soll, bevor er eine weitere Aktualisierungsanfrage sendet. Beachten Sie, dass die empfohlene Wartezeit in der Antwort enthalten sein kann. Weitere Informationen finden Sie unter Anfragehäufigkeit.

URLs prüfen

Um zu prüfen, ob sich eine URL auf einer Web Risk-Liste befindet, muss der Client zuerst den Hash und das Hash-Präfix der URL berechnen. Weitere Informationen finden Sie unter URLs und Hashing. Der Client fragt dann die lokale Datenbank ab, um festzustellen, ob eine Übereinstimmung vorliegt. Wenn das Hash-Präfix in der lokalen Datenbank nicht vorhanden ist, wird die URL als sicher eingestuft (d. h. nicht in den Web Risk-Listen).

Wenn das Hash-Präfix in der lokalen Datenbank vorhanden ist (eine Hash-Präfixkollision), muss der Client das Hash-Präfix zur Prüfung an die Web Risk-Server senden. Die Server geben alle SHA 256-Hashes in voller Länge zurück, die das angegebene Hash-Präfix enthalten. Wenn einer dieser Hashs in voller Länge mit dem Hash der betreffenden URL in voller Länge übereinstimmt, wird die URL als unsicher eingestuft. Wenn keiner der Hashes in voller Länge mit dem Hash in voller Länge der betreffenden URL übereinstimmt, wird diese URL als sicher betrachtet.

Google erfährt zu keinem Zeitpunkt, welche URLs Sie untersuchen. Google erfährt zwar die Hash-Präfixe von URLs, die Hash-Präfixe liefern jedoch nur wenige Informationen zu den tatsächlichen URLs.

Senden Sie eine HTTP-GET-Anfrage an die Methode hashes.search, um zu prüfen, ob sich eine URL auf einer Liste mit Webrisiken befindet:

  • Die HTTP-GET-Anfrage enthält das Hash-Präfix der zu überprüfenden URL.
  • Die HTTP-GET-Antwort gibt die übereinstimmenden Hashes in voller Länge sowie die positive und negative Ablaufzeit zurück.

Beispiel: hashes.search

HTTP-GET-Anfrage

Im folgenden Beispiel werden die Namen von zwei Web Risk-Listen und ein Hash-Präfix zum Vergleich und zur Überprüfung gesendet. Weitere Informationen finden Sie in den hashes.search-Suchparametern und in den Erläuterungen nach dem Codebeispiel.

curl \
  -H "Content-Type: application/json" \
  "https://webrisk.googleapis.com/v1/hashes:search?key=YOUR_API_KEY&threatTypes=MALWARE&threatTypes=SOCIAL_ENGINEERING&hashPrefix=WwuJdQ%3D%3D"

Web Risk-Listen

Das Feld threatTypes gibt die Web Risk-Listen an. Im Beispiel werden zwei Listen identifiziert: MALWARE und SOCIAL_ENGINEERING.

Bedrohungs-Hash-Präfixe

Das Feld hashPrefix enthält das Hash-Präfix der URL, die Sie prüfen möchten. Dieses Feld muss das genaue Hash-Präfix enthalten, das in der lokalen Datenbank vorhanden ist. Wenn das lokale Hash-Präfix beispielsweise 4 Byte lang ist, muss das Feld hashPrefix 4 Byte lang sein. Wenn das lokale Hash-Präfix auf 7 Byte verlängert wurde, muss das Feld hashPrefix 7 Byte lang sein.

HTTP-GET-Antwort

Im folgenden Beispiel gibt die Antwort die übereinstimmenden Bedrohungen zurück, die die entsprechenden Web Risk-Listen sowie die Ablaufzeiten enthalten.

Antworttext

Der Antworttext enthält die Übereinstimmungsinformationen (die Listennamen und die Hashes in voller Länge und die Cache-Dauer). Weitere Informationen finden Sie im Antworttext hashes.search und in den Erläuterungen nach dem Codebeispiel.

{
  "threats": [{
      "threatTypes": ["MALWARE"],
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
      "expireTime": "2019-07-17T15:01:23.045123456Z"
    }, {
      "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
      "hash": "WwuJdQxaCSH453-uytERC456gf45rFExcE23F7-hnfD="
      "expireTime": "2019-07-17T15:01:23.045123456Z"
    },
  }],
  "negativeExpireTime": "2019-07-17T15:01:23.045123456Z"
}

Stimmt überein mit

Das Feld threats gibt übereinstimmende Hashes in voller Länge für das Hash-Präfix zurück. Die URLs, die diesen Hashes entsprechen, gelten als unsicher. Wenn für ein Hash-Präfix keine Übereinstimmung gefunden wird, wird nichts zurückgegeben. Die URL, die diesem Hash-Präfix entspricht, gilt als sicher.

Ablaufzeit

In den Feldern expireTime und negativeExpireTime wird angegeben, wann die Hashes als unsicher bzw. sicher gelten müssen. Weitere Informationen finden Sie unter Caching.