Safe Browsing Lookup API (v4)

Ringkasan

Lookup API memungkinkan aplikasi klien Anda mengirimkan permintaan ke Safe Browsing server untuk memeriksa apakah URL disertakan di salah satu daftar Safe Browsing. Jika URL ditemukan di satu atau lebih banyak daftar, informasi yang cocok akan ditampilkan.

Memeriksa URL

Untuk memeriksa apakah URL ada dalam daftar Safe Browsing, kirim permintaan POST HTTP ke threatMatches.find berikut:

• Permintaan POST HTTP dapat menyertakan 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

Pada contoh berikut, dua daftar Safe Browsing dan tiga URL dikirim ke server untuk menentukan apakah ada kecocokan.

Header permintaan

Header permintaan menyertakan URL permintaan dan jenis konten. Ingatlah untuk mengganti kunci API Anda untuk 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 menyertakan informasi klien (ID dan versi) serta informasi ancaman (nama daftar dan URL). Untuk mengetahui detail selengkapnya, lihat isi permintaanthreatMatches.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 setiap pengguna. (Informasi klien digunakan untuk pencatatan dan penghitungan sisi server. Anda dapat memilih nama apa pun untuk ID klien, tetapi sebaiknya Anda memilih nama yang mewakili identitas sebenarnya klien, seperti nama perusahaan, dibaca sebagai satu kata, dalam huruf kecil semua.)

Daftar Safe Browsing

Kolom threatType, platformType, dan threatEntryType digabungkan untuk mengidentifikasi (nama) daftar Safe Browsing. Dalam contoh ini, dua daftar diidentifikasi: MALWARE/WINDOWS/URL dan SOCIAL_EngineERING/WINDOWS/URL. Sebelum mengirim permintaan, pastikan jenisnya kombinasi yang Anda tentukan valid (lihat Daftar Safe Browsing).

URL ancaman

Dalam contoh, array threatEntries berisi tiga URL (urltocheck1.org, urltocheck2.org, dan urltocheck3.org) yang akan diperiksa berdasarkan dua daftar Safe Browsing.

Catatan: Lookup API dan metode threatMatches harus selalu menggunakan kolom URL, bukan kolom hash (lihat ThreatEntry).

Respons POST HTTP

Dalam contoh berikut, respons menampilkan kecocokan; dua dari tiga URL yang disebutkan dalam ditemukan di salah satu dari dua daftar Safe Browsing yang ditentukan dalam permintaan tersebut.

Header respons

Header respons mencakup kode status HTTP dan jenis kontennya.

HTTP/1.1 200 OK
Content-Type: application/json

Isi respons

Isi respons mencakup informasi kecocokan (nama daftar dan URL yang ditemukan di daftar tersebut, metadata, jika tersedia, dan durasi cache). Untuk mengetahui detail selengkapnya, lihat isi responsthreatMatches.find dan penjelasan yang mengikuti contoh kode.

Catatan: Jika tidak ada kecocokan (yaitu, jika tidak ada URL yang ditentukan dalam permintaan ditemukan di salah satu daftar yang ditentukan dalam permintaan), respons POST HTTP hanya 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 mencantumkan nama daftar Safe Browsing dan URL—jika jika ada kecocokan. Dalam contoh ini, dua URL (urltocheck1.org dan urltocheck2.org) ditemukan di salah satu daftar Safe Browsing (MALWARE/WINDOWS/URL) sehingga informasi yang cocok 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 ancamannya. Saat ini, metadata tersedia untuk daftar Safe Browsing MALWARE/WINDOWS/URL (lihat Metadata).

Durasi cache

Kolom cacheDuration menunjukkan durasi waktu URL harus dianggap tidak aman (lihat Menyimpan ke cache).