Dokumen ini berlaku untuk metode berikut: Update API (v4): threatListUpdates.fetch.
Penyiapan database
Klien yang menggunakan Update API harus menyiapkan database lokal dan melakukan download
awal daftar Safe Browsing yang ingin digunakan. Untuk memulai, Anda dapat mem-build dan men-deploy
paket Go safebrowsing (atau menggunakan paket untuk membuat model implementasi Anda sendiri). Untuk mengetahui informasi selengkapnya,
lihat https://github.com/google/safebrowsing/.
Pembaruan database
Untuk memastikan perlindungan terhadap ancaman terbaru, sangat disarankan bagi klien untuk memperbarui daftar Safe Browsing lokal secara rutin menggunakan metode threatListUpdates.fetch. Permintaan threatListUpdates.fetch menentukan daftar yang akan diperbarui. Jika klien memiliki batasan memori atau bandwidth, mereka juga dapat menggunakan permintaan untuk menetapkan batasan update (lihat Mengupdate Batasan). Respons threatListUpdates.fetch menampilkan update lengkap atau update sebagian untuk setiap daftar, seperti yang dijelaskan di bawah.Update lengkap
Update lengkap ditampilkan saat klien mengosongkan kolom state di permintaan threatListUpdates.fetch atau ketika server menentukan bahwa update penuh diperlukan. Untuk update lengkap, hanya
penambahan yang ditampilkan. Klien
diharapkan dapat menghapus database lokal sebelum menerapkan update dan melakukan
pemeriksaan validasi.
Update lengkap ditampilkan saat klien mengirim permintaan awal untuk sebuah daftar. Dalam hal ini, kolom
state dalam permintaan dibiarkan kosong (karena tidak ada nilai yang dapat diberikan) dan kolom newClientState
dalam respons menampilkan status awal untuk daftar lokal. Update lengkap juga ditampilkan
saat klien sengaja membiarkan kolom state kosong pada permintaan berikutnya. Tindakan ini akan memaksakan
update penuh dan menampilkan status baru di kolom newClientState respons.
Terkadang, server Safe Browsing menampilkan update lengkap jika hanya update sebagian yang diminta oleh klien. Hal ini dapat terjadi jika klien awalnya mendownload versi kecil daftar, lalu mengupdate ke versi daftar yang lebih besar; server akan menampilkan update lengkap dengan seluruh daftar. Hal ini juga dapat terjadi jika klien sudah lama tidak mendownload data dan meminta update parsial; sekali lagi, server hanya akan menampilkan update lengkap yang berisi seluruh daftar.
Update sebagian
Update parsial ditampilkan saat klien memberikan nilai untuk kolom state di permintaan threatListUpdates.fetch (pengecualiannya, seperti yang disebutkan di atas, terjadi saat server menentukan bahwa update penuh diperlukan). Untuk
pembaruan sebagian, penambahan dan
penghapusan ditampilkan. Klien memperbarui
daftar di database lokal (menerapkan penghapusan sebelum penambahan), lalu melakukan
pemeriksaan validasi.
Penambahan
Penambahan adalah awalan hash SHA256 yang harus ditambahkan ke database lokal. Sebagian besar awalan hash panjangnya 4 byte, tetapi beberapa awalan hash bisa memiliki panjang antara 4 hingga 32 byte. Oleh karena itu, beberapa kumpulan tambahan dapat ditampilkan; misalnya, satu berisi awalan 4 byte dan satu lagi berisi awalan 5 byte.
Jika klien mendukung kompresi, respons mungkin dikompresi menggunakan kompresi Rice. Namun, hanya awalan hash 4 byte yang dikompresi. Awalan hash yang lebih panjang selalu dikirim dalam format mentah yang tidak dikompresi (lihat Kompresi).
Penghapusan
Penghapusan adalah indeks berbasis nol dalam database klien yang diurutkan secara leksikografis yang mengarah pada entri yang harus dihapus dari database lokal. Hanya satu kumpulan penghapusan yang akan dikembalikan.
Jika klien mendukung kompresi, "hash beras" dan "indeks beras" akan ditampilkan. Jika kompresi tidak didukung, "hash mentah" dan "indeks mentah" akan ditampilkan (lihat Kompresi).
Pemeriksaan validasi
Saat respons threatListUpdates.fetch ditampilkan—dengan update penuh atau update sebagian—klien diharapkan untuk melakukan pemeriksaan validasi.
Pertama-tama, klien akan memperbarui daftar di database lokal (menerapkan penghapusan sebelum penambahan). Klien kemudian menghitung hash SHA256 dari daftar lokal (diurutkan secara leksikografis) dan membandingkannya dengan checksum yang ditampilkan dalam respons. Jika kedua nilai tersebut sama, daftar Safe Browsing dianggap "benar".
Jika kedua nilai tersebut tidak sama, daftar Safe Browsing dianggap "rusak". Klien harus menghapus daftar dari database dan menerbitkan ulang pembaruan kedua dengan kolom state yang disetel ke string kosong; tindakan ini akan memaksa pembaruan penuh serta menampilkan daftar dan status baru.