Migration From V4
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Jednym z najważniejszych ulepszeń Bezpiecznego przeglądania Google w wersji 5 w porównaniu z wersją 4 (a konkretnie interfejsem Update API w wersji 4) jest aktualność i zakres danych. Ponieważ ochrona w dużej mierze zależy od lokalnej bazy danych utrzymywanej przez klienta, opóźnienie i rozmiar aktualizacji lokalnej bazy danych są głównymi czynnikami wpływającymi na brak ochrony. W wersji 4 typowy klient potrzebuje od 20 do 50 minut, aby uzyskać najnowszą wersję list zagrożeń. Niestety ataki phishingowe szybko się rozprzestrzeniają: w 2021 r. 60% witryn, które przeprowadzają ataki, działało krócej niż 10 minut. Z naszych analiz wynika, że około 25–30% brakującej ochrony przed phishingiem wynika z nieaktualności danych. Niektóre urządzenia nie są też przystosowane do zarządzania wszystkimi listami zagrożeń Bezpiecznego przeglądania Google, które z czasem stają się coraz większe.
Jeśli obecnie używasz interfejsu Update API w wersji 4, możesz bezproblemowo przejść z wersji 4 na wersję 5 bez konieczności resetowania ani usuwania lokalnej bazy danych. W tej sekcji znajdziesz instrukcje, jak to zrobić.
Aktualizacje list konwersji
W przeciwieństwie do wersji 4, w której listy są identyfikowane przez krotkę typu zagrożenia, typu platformy i typu wpisu zagrożenia, w wersji 5 listy są identyfikowane po prostu przez nazwę. Zapewnia to elastyczność, gdy wiele list w wersji 5 może mieć ten sam typ zagrożenia. W wersji 5 usunęliśmy typy platform i rodzaje zagrożeń.
W wersji 4 do pobierania list używa się metody threatListUpdates.fetch. W wersji 5 przełącza się na metodę hashLists.batchGet.
W żądaniu należy wprowadzić te zmiany:
- Całkowicie usuń obiekt
ClientInfo v4. Zamiast podawać identyfikator klienta w odpowiednim polu, użyj znanego nagłówka User-Agent. Nie ma określonego formatu podawania identyfikatora klienta w tym nagłówku, ale sugerujemy po prostu podanie oryginalnego identyfikatora klienta i wersji klienta oddzielonych spacją lub ukośnikiem.
- Dla każdego obiektu
ListUpdateRequest w wersji 4:
- Znajdź odpowiednią nazwę listy w wersji 5 na liście dostępnych list i podaj ją w żądaniu w wersji 5.
- Usuń niepotrzebne pola, takie jak
threat_entry_type lub platform_type.
- Pole
state w wersji 4 jest bezpośrednio zgodne z polem versions w wersji 5. Ten sam ciąg bajtów, który byłby wysyłany na serwer w polu state w wersji 4, można po prostu wysłać w wersji 5 w polu versions.
- W przypadku ograniczeń w wersji 4 w wersji 5 używana jest uproszczona wersja o nazwie
SizeConstraints. Dodatkowe pola, takie jak region, powinny zostać pominięte.
W odpowiedzi należy wprowadzić te zmiany:
- Wersja 4 wyliczenia
ResponseType jest po prostu zastępowana polem logicznym o nazwie partial_update.
- Pole
minimum_wait_duration może teraz mieć wartość zero lub zostać pominięte. Jeśli tak jest, klient jest proszony o natychmiastowe przesłanie kolejnego żądania. Dzieje się tak tylko wtedy, gdy klient określi w SizeConstraints mniejsze ograniczenie maksymalnego rozmiaru aktualizacji niż maksymalny rozmiar bazy danych.
- Algorytm dekodowania Rice dla 32-bitowych liczb całkowitych będzie wymagał dostosowania. Różnica polega na tym, że zakodowane dane są zakodowane z inną kolejnością bajtów. Zarówno w wersji 4, jak i w wersji 5 32-bitowe prefiksy skrótu są sortowane leksykograficznie. W wersji 4 te prefiksy są traktowane jako little endian podczas sortowania, a w wersji 5 – jako big endian. Oznacza to, że klient nie musi niczego sortować, ponieważ sortowanie leksykograficzne jest identyczne z sortowaniem numerycznym w formacie big endian. Przykład takiego kodu w implementacji v4 w Chromium znajdziesz tutaj. Takie sortowanie można usunąć.
- Algorytm dekodowania Rice’a będzie musiał być zaimplementowany również w przypadku innych długości skrótu.
Konwertowanie wyszukiwań haszów
W wersji 4 do pobierania pełnych skrótów używa się metody fullHashes.find. Odpowiednikiem tej metody w wersji 5 jest metoda hashes.search.
W żądaniu należy wprowadzić te zmiany:
- Skonstruuj kod tak, aby wysyłać tylko prefiksy skrótu o długości dokładnie 4 bajtów.
- Całkowicie usuń obiekty
ClientInfowersji 4. Zamiast podawać identyfikator klienta w odpowiednim polu, użyj znanego nagłówka User-Agent. Nie ma określonego formatu podawania identyfikatora klienta w tym nagłówku, ale sugerujemy po prostu podanie oryginalnego identyfikatora klienta i wersji klienta oddzielonych spacją lub ukośnikiem.
- Usuń pole
client_states. Nie jest już potrzebny.
- Nie musisz już uwzględniać pola
threat_types ani podobnych pól.
W odpowiedzi należy wprowadzić te zmiany:
- Pole
minimum_wait_duration zostało usunięte. Klient może w razie potrzeby zawsze wysłać nowe żądanie.
- Obiekt v4
ThreatMatch został uproszczony do obiektu FullHash.
- Buforowanie zostało uproszczone do jednego czasu trwania pamięci podręcznej. Aby dowiedzieć się, jak korzystać z pamięci podręcznej, zapoznaj się z procedurami opisanymi powyżej.
O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.
Ostatnia aktualizacja: 2025-08-10 UTC.
[null,null,["Ostatnia aktualizacja: 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."]]
