Ringkasan
Lookup API memungkinkan aplikasi klien Anda mengirim permintaan ke server Safe Browsing untuk memeriksa apakah URL disertakan dalam daftar Safe Browsing mana pun. Jika URL ditemukan di satu atau beberapa daftar, informasi yang cocok akan ditampilkan.
Memeriksa URL
Untuk memeriksa apakah URL ada dalam daftar Safe Browsing, kirim permintaan POST
HTTP ke metode threatMatches.find:
- Permintaan
POST
HTTP dapat mencakup hingga 500 URL. URL harus valid (lihat RFC 2396), tetapi tidak perlu dikanonikalisasi atau dienkode. - Respons
POST
HTTP menampilkan URL yang cocok beserta durasi cache.
Contoh: ancamanMatches.find
Permintaan POST HTTP
Dalam contoh berikut, dua daftar Safe Browsing dan tiga URL dikirim ke server untuk menentukan apakah ada kecocokan.
Header permintaan
Header permintaan mencakup URL permintaan dan jenis konten. Jangan lupa mengganti kunci API Anda dengan API_KEY
di URL.
POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Isi permintaan
Isi permintaan mencakup informasi klien (ID dan versi) serta informasi ancaman (nama daftar dan URL). Untuk mengetahui detail selengkapnya, lihat isi permintaan threatMatches.find dan penjelasan yang mengikuti contoh kode.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "threatInfo": { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "platformTypes": ["WINDOWS"], "threatEntryTypes": ["URL"], "threatEntries": [ {"url": "http://www.urltocheck1.org/"}, {"url": "http://www.urltocheck2.org/"}, {"url": "http://www.urltocheck3.com/"} ] } }
Informasi klien
Kolom clientID
dan clientVersion
harus mengidentifikasi implementasi klien secara unik, bukan
pengguna individual. (Informasi klien digunakan untuk pencatatan log dan akuntansi sisi server. Anda dapat memilih nama apa pun untuk client ID, tetapi sebaiknya pilih nama yang mewakili identitas sebenarnya klien, seperti nama perusahaan Anda, yang ditampilkan sebagai satu kata, dalam huruf kecil semua.)
Daftar Safe Browsing
Kolom threatType
, platformType
, dan threatEntryType
digabungkan untuk mengidentifikasi daftar Safe Browsing (nama). Pada contoh, dua daftar diidentifikasi: MALWARE/WINDOWS/URL dan SOCIAL_EngineERING/WINDOWS/URL. Sebelum mengirim permintaan, pastikan kombinasi jenis
yang Anda tentukan valid (lihat Daftar Safe Browsing).
URL Ancaman
Pada contoh, array threatEntries
berisi tiga URL (urltocheck1.org, urltocheck2.org, dan urltocheck3.org) yang akan diperiksa dengan dua daftar Safe Browsing.
Catatan: Lookup API dan metode threatMatches
harus selalu menggunakan kolom URL
,
bukan kolom hash
(lihat ThreatEntry).
Respons POST HTTP
Pada contoh berikut, respons menampilkan kecocokan; dua dari tiga URL yang ditentukan dalam permintaan ditemukan pada salah satu dari dua daftar Safe Browsing yang ditentukan dalam permintaan.
Header respons
Header respons mencakup kode status HTTP dan jenis konten.
HTTP/1.1 200 OK Content-Type: application/json
Isi respons
Isi respons menyertakan informasi pencocokan (nama daftar dan URL yang ditemukan di daftar tersebut, metadata, jika tersedia, dan durasi cache). Untuk mengetahui detail selengkapnya, lihat isi respons threatMatches.find dan penjelasan yang mengikuti contoh kode.
Catatan: Jika tidak ada kecocokan (yaitu, jika tidak ada URL yang ditentukan dalam permintaan yang ditemukan di salah satu daftar yang ditentukan dalam permintaan), respons POST
HTTP hanya akan menampilkan objek kosong dalam isi respons.
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": {"url": "http://www.urltocheck1.org/"}, "threatEntryMetadata": { "entries": [{ "key": "malware_threat_type", "value": "landing" }] }, "cacheDuration": "300.000s" }, { "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": {"url": "http://www.urltocheck2.org/"}, "threatEntryMetadata": { "entries": [{ "key": "malware_threat_type", "value": "landing" }] }, "cacheDuration": "300.000s" }] }
Kecocokan
Objek matches
akan mencantumkan nama daftar Safe Browsing dan URL—jika
ada kecocokan. Pada contoh, dua URL (urltocheck1.org dan urltocheck2.org) ditemukan di salah satu daftar Safe Browsing (MALWARE/WINDOWS/URL) sehingga informasi yang cocok akan ditampilkan. URL ketiga (urltocheck3.org) tidak ditemukan di kedua daftar, sehingga tidak ada informasi yang ditampilkan untuk URL ini.
Metadata
Kolom threatEntryMetadata
bersifat opsional dan memberikan informasi tambahan tentang pencocokan ancaman. Saat ini, metadata tersedia untuk daftar Safe Browsing MALWARE/WINDOWS/URL
(lihat Metadata).
Durasi cache
Kolom cacheDuration
menunjukkan berapa lama URL harus dianggap tidak aman (lihat Caching).