Safe Browsing Lookup API (v4)

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).