Migration From V4
Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Salah satu peningkatan signifikan Google Safe Browsing v5 dibandingkan v4 (khususnya, Update API v4) adalah keaktualan dan cakupan data. Karena perlindungan sangat bergantung pada database lokal yang dikelola klien, penundaan dan ukuran update database lokal adalah penyebab utama perlindungan yang terlewatkan. Di v4, klien biasanya memerlukan waktu 20 hingga 50 menit untuk mendapatkan versi terbaru daftar ancaman. Sayangnya, serangan phishing menyebar dengan cepat: pada tahun 2021, 60% situs yang melancarkan serangan aktif kurang dari 10 menit. Analisis kami menunjukkan bahwa sekitar 25-30% perlindungan phishing yang hilang disebabkan oleh data yang sudah tidak berlaku. Selain itu, beberapa perangkat tidak dilengkapi untuk mengelola seluruh daftar ancaman Google Safe Browsing, yang terus bertambah besar dari waktu ke waktu.
Jika saat ini Anda menggunakan Update API v4, ada jalur migrasi yang lancar dari v4 ke v5 tanpa harus mereset atau menghapus database lokal. Bagian ini mendokumentasikan cara melakukannya.
Pembaruan Daftar Konversi
Tidak seperti V4, yang mengidentifikasi daftar berdasarkan tuple jenis ancaman, jenis platform, jenis entri ancaman, di v5 daftar diidentifikasi hanya berdasarkan nama. Hal ini memberikan fleksibilitas saat beberapa daftar v5 dapat berbagi jenis ancaman yang sama. Jenis platform dan jenis entri ancaman dihapus di v5.
Di v4, pengguna akan menggunakan threatListUpdates.fetch method untuk mendownload daftar. Di v5, Anda dapat beralih ke hashLists.batchGet method.
Perubahan berikut harus dilakukan pada permintaan:
- Hapus objek v4
ClientInfo sepenuhnya. Daripada memberikan identifikasi klien menggunakan kolom khusus, cukup gunakan header User-Agent yang sudah dikenal. Meskipun tidak ada format yang ditentukan untuk memberikan identifikasi klien di header ini, sebaiknya cukup sertakan ID klien dan versi klien asli yang dipisahkan oleh karakter spasi atau karakter garis miring.
- Untuk setiap objek v4
ListUpdateRequest:
- Cari nama daftar v5 yang sesuai dari available lists dan berikan nama tersebut dalam permintaan v5.
- Hapus kolom yang tidak diperlukan seperti
threat_entry_type atau platform_type.
- Kolom
state di v4 kompatibel langsung dengan kolom versions v5. String byte yang sama yang akan dikirim ke server menggunakan kolom state di v4 dapat dikirim di v5 menggunakan kolom versions.
- Untuk batasan v4, v5 menggunakan versi sederhana yang disebut
SizeConstraints. Kolom tambahan seperti region harus dihapus.
Perubahan berikut harus dilakukan pada respons:
- enum
ResponseType v4 diganti dengan kolom boolean bernama partial_update.
- Kolom
minimum_wait_duration sekarang dapat berupa nol atau dihilangkan. Jika ya, klien diminta untuk segera membuat permintaan lain. Hal ini hanya terjadi jika klien menentukan batasan yang lebih kecil pada ukuran update maksimum daripada ukuran database maksimum di SizeConstraints.
- Algoritma decoding Rice untuk bilangan bulat 32-bit perlu disesuaikan. Perbedaannya adalah data yang dienkode dienkode dengan endianness yang berbeda. Di v4 dan v5, awalan hash 32-bit diurutkan secara leksikografis. Namun, di v4, awalan tersebut diperlakukan sebagai little endian saat diurutkan, sedangkan di v5, awalan tersebut diperlakukan sebagai big endian saat diurutkan. Artinya, klien tidak perlu melakukan pengurutan apa pun, karena pengurutan leksikografis identik dengan pengurutan numerik dengan big endian. Contoh jenis ini dalam penerapan v4 di Chromium dapat ditemukan di sini. Pengurutan tersebut dapat dihapus.
- Algoritma decoding Rice juga perlu diterapkan untuk panjang hash lainnya.
Mengonversi Penelusuran Hash
Di v4, orang akan menggunakan metode fullHashes.find untuk mendapatkan hash lengkap. Metode yang setara di v5 adalah metode hashes.search.
Perubahan berikut harus dilakukan pada permintaan:
- Strukturkan kode untuk hanya mengirimkan awalan hash yang panjangnya tepat 4 byte.
- Hapus objek v4
ClientInfo sepenuhnya. Daripada memberikan identifikasi klien menggunakan kolom khusus, cukup gunakan header User-Agent yang sudah dikenal. Meskipun tidak ada format yang ditentukan untuk memberikan identifikasi klien di header ini, sebaiknya cukup sertakan ID klien dan versi klien asli yang dipisahkan oleh karakter spasi atau karakter garis miring.
- Hapus kolom
client_states. Fungsi tersebut tidak diperlukan lagi.
- Tidak perlu lagi menyertakan
threat_types dan kolom serupa.
Perubahan berikut harus dilakukan pada respons:
- Kolom
minimum_wait_duration telah dihapus. Klien selalu dapat mengeluarkan permintaan baru sesuai kebutuhan.
- Objek v4
ThreatMatch telah disederhanakan menjadi objek FullHash.
- Penyimpanan dalam cache telah disederhanakan menjadi durasi cache tunggal. Lihat prosedur di atas untuk berinteraksi dengan cache.
Kecuali dinyatakan lain, konten di halaman ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 4.0, sedangkan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Situs Google Developers. Java adalah merek dagang terdaftar dari Oracle dan/atau afiliasinya.
Terakhir diperbarui pada 2025-08-10 UTC.
[null,null,["Terakhir diperbarui pada 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."]]
