Migration From V4
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Eine wichtige Verbesserung von Google Safe Browsing v5 gegenüber v4 (insbesondere der v4 Update API) ist die Aktualität und Abdeckung der Daten. Da der Schutz stark von der vom Client verwalteten lokalen Datenbank abhängt, sind die Verzögerung und die Größe der Aktualisierung der lokalen Datenbank die Hauptursache für den fehlenden Schutz. In Version 4 dauert es in der Regel 20 bis 50 Minuten, bis der Client die aktuelle Version der Bedrohungslisten abruft. Leider breiten sich Phishing-Angriffe schnell aus: 2021 waren 60% der Websites, die Angriffe ausführen, weniger als 10 Minuten lang aktiv. Unsere Analyse zeigt, dass etwa 25–30% des fehlenden Phishingschutzes auf solche veralteten Daten zurückzuführen sind. Außerdem sind einige Geräte nicht in der Lage, die gesamten Google Safe Browsing-Bedrohungslisten zu verwalten, die im Laufe der Zeit immer größer werden.
Wenn Sie derzeit die v4 Update API verwenden, gibt es einen nahtlosen Migrationspfad von v4 zu v5, ohne dass die lokale Datenbank zurückgesetzt oder gelöscht werden muss. In diesem Abschnitt wird beschrieben, wie Sie das tun.
Aktualisierungen bei der Umstellung von Listen
Im Gegensatz zu V4, wo Listen durch das Tupel aus Bedrohungstyp, Plattformtyp und Bedrohungseintragstyp identifiziert werden, werden Listen in V5 einfach durch den Namen identifiziert. Das bietet Flexibilität, wenn mehrere v5-Listen denselben Bedrohungstyp verwenden. Plattformtypen und Typen von Bedrohungseinträgen werden in Version 5 entfernt.
In Version 4 wurde die Methode threatListUpdates.fetch zum Herunterladen von Listen verwendet. In Version 5 würde man zur hashLists.batchGet-Methode wechseln.
Die folgenden Änderungen sollten an der Anfrage vorgenommen werden:
- Entfernen Sie das v4
ClientInfo-Objekt vollständig. Anstatt die Identifizierung eines Clients über ein separates Feld anzugeben, verwenden Sie einfach den bekannten User-Agent-Header. Es gibt kein vorgeschriebenes Format für die Angabe der Client-ID in diesem Header. Wir empfehlen, einfach die ursprüngliche Client-ID und Client-Version durch ein Leerzeichen oder einen Schrägstrich getrennt anzugeben.
- Für jedes v4-
ListUpdateRequest-Objekt:
- Suchen Sie in den verfügbaren Listen nach dem entsprechenden v5-Listennamen und geben Sie diesen Namen in der v5-Anfrage an.
- Entfernen Sie nicht benötigte Felder wie
threat_entry_type oder platform_type.
- Das Feld
state in Version 4 ist direkt mit dem Feld versions in Version 5 kompatibel. Derselbe Byte-String, der in Version 4 über das Feld state an den Server gesendet wurde, kann in Version 5 einfach über das Feld versions gesendet werden.
- Für die v4-Einschränkungen wird in v5 eine vereinfachte Version namens
SizeConstraints verwendet. Zusätzliche Felder wie region sollten entfernt werden.
Die folgenden Änderungen sollten an der Antwort vorgenommen werden:
- Das v4-Enum
ResponseType wird einfach durch ein boolesches Feld mit dem Namen partial_update ersetzt.
- Das Feld
minimum_wait_duration kann jetzt null sein oder weggelassen werden. Ist dies der Fall, wird der Client aufgefordert, sofort eine weitere Anfrage zu stellen. Dies geschieht nur, wenn der Client in SizeConstraints eine kleinere Einschränkung für die maximale Aktualisierungsgröße als für die maximale Datenbankgröße angibt.
- Der Rice-Decodierungsalgorithmus für 32‑Bit-Ganzzahlen muss angepasst werden. Der Unterschied besteht darin, dass die codierten Daten mit einer anderen Endianness codiert werden. Sowohl in Version 4 als auch in Version 5 werden 32-Bit-Hash-Präfixe lexikografisch sortiert. In Version 4 werden diese Präfixe beim Sortieren als Little-Endian behandelt, in Version 5 als Big-Endian. Das bedeutet, dass der Client keine Sortierung vornehmen muss, da die lexikografische Sortierung mit Big-Endian-Sortierung identisch ist. Ein Beispiel für diese Art von Sortierung in der Chromium-Implementierung von Version 4 finden Sie hier. Diese Sortierung kann entfernt werden.
- Der Rice-Decodierungsalgorithmus muss auch für andere Hash-Längen implementiert werden.
Hash-Suchanfragen mit Conversion
In Version 4 würde man die fullHashes.find-Methode verwenden, um vollständige Hashes abzurufen. Die entsprechende Methode in Version 5 ist hashes.search.
Die folgenden Änderungen sollten an der Anfrage vorgenommen werden:
- Strukturieren Sie den Code so, dass nur Hash-Präfixe mit einer Länge von genau 4 Byte gesendet werden.
- Entfernen Sie die v4-
ClientInfo-Objekte vollständig. Anstatt die Identifizierung eines Clients über ein separates Feld anzugeben, verwenden Sie einfach den bekannten User-Agent-Header. Es gibt kein vorgeschriebenes Format für die Angabe der Client-ID in diesem Header. Wir empfehlen, einfach die ursprüngliche Client-ID und Client-Version durch ein Leerzeichen oder einen Schrägstrich getrennt anzugeben.
- Entfernen Sie das Feld
client_states. Das ist nicht mehr erforderlich.
- Es ist nicht mehr erforderlich,
threat_types und ähnliche Felder anzugeben.
Die folgenden Änderungen sollten an der Antwort vorgenommen werden:
- Das Feld
minimum_wait_duration wurde entfernt. Der Client kann bei Bedarf jederzeit eine neue Anfrage senden.
- Das v4-Objekt
ThreatMatch wurde in das FullHash-Objekt vereinfacht.
- Das Caching wurde auf eine einzige Cache-Dauer vereinfacht. Informationen zur Interaktion mit dem Cache finden Sie oben.
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2025-08-10 (UTC).
[null,null,["Zuletzt aktualisiert: 2025-08-10 (UTC)."],[],[],null,["# Migration From V4\n\nOne significant improvement of Google Safe Browsing v5 over v4 (specifically, [the v4 Update API](/safe-browsing/v4/update-api)) is data freshness and coverage. Since the protection highly depends on the client-maintained local database, the delay and size of the local database update is the main contributor of the missed protection. In v4, the typical client takes 20 to 50 minutes to obtain the most up-to-date version of threat lists. Unfortunately, phishing attacks spread fast: as of 2021, 60% of sites that deliver attacks live less than 10 minutes. Our analysis shows that around 25-30% of missing phishing protection is due to such data staleness. Further, some devices are not equipped to manage the entirety of the Google Safe Browsing threat lists, which continues to grow larger over time.\n\nIf you are currently using the [v4 Update API](/safe-browsing/v4/update-api), there is a seamless migration path from v4 to v5 without having to reset or erase the local database. This section documents how to do that.\n\n### Converting List Updates\n\nUnlike V4, where lists are identified by the tuple of threat type, platform type, threat entry type, in v5 lists are simply identified by name. This provides flexibility when multiple v5 lists could share the same threat type. Platform types and threat entry types are removed in v5.\n\nIn v4, one would use the [threatListUpdates.fetch method](/safe-browsing/reference/rest/v4/threatListUpdates/fetch) to download lists. In v5, one would switch to the [hashLists.batchGet method](/safe-browsing/reference/rest/v5/hashLists/batchGet).\n\nThe following changes should be made to the request:\n\n1. Remove the [v4 `ClientInfo` object](/safe-browsing/reference/rest/v4/ClientInfo) altogether. Instead of supplying a client's identification using a dedicated field, simply use the well-known [User-Agent header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). While there is no prescribed format for supplying the client identification in this header, we suggest simply including the original client ID and client version separated by a space character or a slash character.\n2. For each [v4 `ListUpdateRequest` object](/safe-browsing/reference/rest/v4/threatListUpdates/fetch#listupdaterequest):\n - Look up the corresponding v5 list name from the [available lists](/safe-browsing/reference/Local.Database#available-lists) and supply that name in the v5 request.\n - Remove unneeded fields such as `threat_entry_type` or `platform_type`.\n - The `state` field in v4 is directly compatible with the v5 `versions` field. The same byte string that would be sent to the server using the `state` field in v4 can simply be sent in v5 using the `versions` field.\n - For the v4 constraints, v5 uses a simplified version called [`SizeConstraints`](/safe-browsing/reference/rest/v5/SizeConstraints). Additional fields such as `region` should be dropped.\n\nThe following changes should be made to the response:\n\n1. The v4 [enum `ResponseType`](/safe-browsing/reference/rest/v4/threatListUpdates/fetch#ResponseType) is simply replaced by a boolean field named `partial_update`.\n2. The `minimum_wait_duration` field can now be zero or omitted. If it is, the client is requested to immediately make another request. This only happens when the client specifies in `SizeConstraints` a smaller constraint on max update size than the max database size.\n3. The Rice decoding algorithm for 32-bit integers will need to be adjusted. The difference is that the encoded data are encoded with a different endianness. In both v4 and v5, 32-bit hash prefixes are sorted lexicographically. But in v4, those prefixes are treated as little endian when sorted, whereas in v5 those prefixes are treated as big endian when sorted. This means that the client does not need to do any sorting, since lexicographic sorting is identical to numeric sorting with big endian. An example of this sort in the Chromium implementation of v4 can be found [here](https://source.chromium.org/chromium/chromium/src/+/main:components/safe_browsing/core/browser/db/v4_rice.cc;l=144-146;drc=8ba1bad80dc22235693a0dd41fe55c0fd2dbdabd). Such sorting can be removed.\n4. The Rice decoding algorithm will need to be implemented for other hash lengths as well.\n\n### Converting Hash Searches\n\nIn v4, one would use the [fullHashes.find method](/safe-browsing/reference/rest/v4/fullHashes/find) to get full hashes. The equivalent method in v5 is [the hashes.search method](/safe-browsing/reference/rest/v5/hashes/search).\n\nThe following changes should be made to the request:\n\n1. Structure the code to only send hash prefixes that are exactly 4 bytes in length.\n2. Remove the [v4 `ClientInfo` objects](/safe-browsing/reference/rest/v4/ClientInfo) altogether. Instead of supplying a client's identification using a dedicated field, simply use the well-known [User-Agent header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). While there is no prescribed format for supplying the client identification in this header, we suggest simply including the original client ID and client version separated by a space character or a slash character.\n3. Remove the `client_states` field. It is no longer necessary.\n4. It is no longer needed to include `threat_types` and similar fields.\n\nThe following changes should be made to the response:\n\n1. The `minimum_wait_duration` field has been removed. The client can always issue a new request on an as-needed basis.\n2. The [v4 `ThreatMatch` object](/safe-browsing/reference/rest/v4/ThreatMatch) has been simplified into the [`FullHash`](/safe-browsing/reference/rest/v5/hashes/search#FullHash) object.\n3. Caching has been simplified into a single cache duration. See the above procedures for interacting with the cache."]]
