Update API verwenden
Übersicht
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&key=API_KEY
Senden Sie die Anfrage mithilfe einer der folgenden Optionen:
curl
Führen Sie folgenden Befehl aus:
curl -X GET \
"https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY"
PowerShell
Führen Sie folgenden Befehl aus:
$headers = @{ }
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&key=API_KEY" | Select-Object -Expand Content
Sie sollten eine JSON-Antwort ähnlich wie diese 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=" } }
Java
Python
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 festlegen, um Speicher- und Bandbreitenbeschränkungen zu vermeiden und ein zu starkes Wachstum der Liste zu verhindern. 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.
Empfohlene nächste Diff
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
-Abfrageparametern 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"
Java
Python
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.