Halaman ini diterjemahkan oleh Cloud Translation API.

API Pembaruan Safe Browsing (v4)

Ringkasan

Update API memungkinkan aplikasi klien Anda mendownload versi hash daftar Safe Browsing untuk tersimpan di {i>database<i} lokal. URL kemudian dapat diperiksa secara lokal. Hanya jika kecocokan ditemukan di lokal, apakah klien perlu mengirim permintaan ke server Safe Browsing untuk memverifikasi apakah URL disertakan di daftar Safe Browsing.

Sebelum menggunakan Update API, Anda perlu menyiapkan database lokal. Safe Browsing menyediakan paket Go yang dapat Anda gunakan untuk memulai. Untuk mengetahui detail selengkapnya, lihat bagian Penyiapan Database di bagian Database Lokal.

Memperbarui database lokal

Agar tetap mendapatkan informasi terkini, klien diwajibkan untuk memperbarui daftar Safe Browsing secara berkala dalam database lokal. Untuk menghemat bandwidth, klien mendownload awalan hash URL, bukan URL mentah. Misalnya, jika "www.badurl.com/" ada dalam daftar Penjelajahan Aman, klien mengunduh Awalan hash SHA256 dari URL tersebut, bukan URL itu sendiri. Dalam kebanyakan kasus, {i>hash<i} panjang awalan 4 byte, yang berarti bahwa biaya bandwidth rata-rata dari mendownload satu daftar adalah 4 byte sebelum kompresi.

Untuk memperbarui daftar Safe Browsing di database lokal, kirim permintaan POST HTTP ke threatListUpdates.fetch berikut:

Permintaan POST HTTP menyertakan nama daftar yang akan diperbarui beserta berbagai batasan klien untuk memperhitungkan batasan memori dan bandwidth.
Respons POST HTTP menampilkan update lengkap atau update parsial. Responsnya mungkin juga menampilkan durasi tunggu minimum.

Contoh: ancamanListUpdates.fetch

Permintaan POST HTTP

Pada contoh berikut, pembaruan untuk satu daftar Safe Browsing diminta.

Header permintaan

Header permintaan menyertakan URL permintaan dan jenis konten. Ingatlah untuk mengganti API Anda untuk API_KEY di URL.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

Isi permintaan

Isi permintaan mencakup informasi klien (ID dan versi) serta informasi update ( nama daftar, status daftar, dan batasan klien). Untuk mengetahui detail selengkapnya, lihat threatListUpdates.fetch isi permintaan dan penjelasan yang mengikuti contoh kode.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

Informasi klien

Kolom clientID dan clientVersion harus mengidentifikasi implementasi klien secara unik, bukan pengguna perorangan. (Informasi klien digunakan dalam logging 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, satu daftar diidentifikasi: MALWARE/WINDOWS/URL. Sebelum mengirim permintaan, pastikan kombinasi jenis yang Anda tetapkan valid (lihat Daftar Safe Browsing).

Status klien

Kolom state menyimpan status klien saat ini dari daftar Safe Browsing. (Status klien ditampilkan di kolom newClientState kolom responsthreatListUpdates.fetch.) Untuk pembaruan awal, kosongkan kolom state.

Batasan ukuran

Kolom maxUpdateEntries menentukan jumlah total update yang dapat dikelola klien (dalam contoh, 2048). Kolom maxDatabaseEntries menentukan jumlah total entri lokal yang dapat dikelola database (dalam contoh, 4096). Klien harus menetapkan batasan ukuran untuk melindungi keterbatasan memori dan bandwidth serta untuk melindungi pertumbuhan bisnis. Untuk informasi selengkapnya, (lihat Update Constraints).

Kompresi yang didukung

Kolom supportedCompressions mencantumkan jenis kompresi yang didukung klien. Di kolom misalnya, klien hanya mendukung data mentah yang tidak dikompresi. Namun, Safe Browsing mendukung jenis kompresi (lihat Kompresi).

Respons POST HTTP

Dalam contoh ini, respons menampilkan pembaruan sebagian untuk daftar Safe Browsing menggunakan jenis kompresi yang diminta.

Header respons

Header respons mencakup kode status HTTP dan jenis konten. Klien yang menerima kode status selain HTTP/200 harus memasuki mode back-off (lihat Frekuensi Permintaan).

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

Isi respons

Isi respons mencakup informasi pembaruan (nama daftar, jenis respons, penambahan dan penghapusan yang akan diterapkan ke {i>database<i} lokal, klien baru status, dan {i>checksum<i}). Dalam contoh, respons juga menyertakan durasi tunggu minimum. Untuk selengkapnya selengkapnya, lihat isi responsthreatListUpdates.fetch dan penjelasan yang mengikuti contoh kode.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

Update database

Kolom responseType akan menunjukkan pembaruan sebagian atau penuh. Sebagai contoh, update parsial ditampilkan, sehingga responsnya mencakup penambahan dan penghapusan. Mungkin ada beberapa kumpulan penambahan, tetapi hanya satu kumpulan penghapusan (lihat Pembaruan Database).

Status klien baru

Kolom newClientState menyimpan status klien baru untuk daftar Safe Browsing yang baru diperbarui. Klien harus menyimpan status klien baru untuk permintaan update berikutnya (kolom state di kolom permintaanthreatListUpdates.fetch atau kolom clientStates di kolom permintaan fullHashes.find).

Checksums

Checksum memungkinkan klien memverifikasi bahwa database lokal tidak mengalami kerusakan apa pun. Jika checksum tidak cocok, klien harus menghapus database dan menerbitkan ulang update dengan kolom state kosong. Namun, klien dalam situasi ini tetap harus mengikuti interval waktu untuk update (lihat Frekuensi Permintaan).

Durasi tunggu minimum

Kolom minimumWaitDuration menunjukkan bahwa klien harus menunggu 593,44 detik (9,89 menit) sebelum mengirim permintaan update lainnya. Perhatikan bahwa periode tunggu dapat atau tidak dapat disertakan dalam respons (lihat Frekuensi Permintaan).

Memeriksa URL

Untuk memeriksa apakah URL ada dalam daftar Safe Browsing, klien harus menghitung hash dan hash terlebih dahulu awalan URL (lihat URL dan Hashing). Klien kemudian mengkueri database lokal untuk menentukan apakah ada kecocokan. Jika awalan hash adalah tidak ada di database lokal, maka URL tersebut dianggap aman (tidak berada di Melihat daftar).

Jika awalan hash ada di database lokal (tumbukan awalan hash), klien harus mengirim awalan {i>hash <i}ke server Safe Browsing untuk diverifikasi. Server akan menampilkan semua hash SHA 256 panjang penuh yang berisi awalan hash yang diberikan. Jika salah satu {i>hash<i} lengkap tersebut cocok dengan {i>hash<i} seluruh URL yang dimaksud, maka URL-nya dianggap tidak aman. Jika tidak ada hash panjang penuh yang cocok dengan hash panjang penuh URL yang dimaksud, URL tersebut dianggap aman.

Google tidak akan pernah mengetahui URL yang Anda periksa. Google mempelajari hash awalan URL, tetapi awalan hash tidak memberikan banyak informasi tentang URL yang sebenarnya.

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

Permintaan POST HTTP dapat menyertakan hingga 500 entri ancaman.
Permintaan POST HTTP mencakup awalan hash URL yang akan diperiksa. Klien dianjurkan untuk mengelompokkan beberapa entri ancaman ke dalam satu permintaan untuk mengurangi penggunaan bandwidth.
Respons POST HTTP menampilkan hash panjang penuh yang cocok beserta durasi cache positif dan negatif. Respons dapat juga menampilkan durasi tunggu minimum.

Contoh: fullHashes.find

Permintaan POST HTTP

Dalam contoh berikut, nama dua daftar Safe Browsing dan tiga awalan hash dikirim untuk perbandingan dan verifikasi.

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/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

Isi permintaan

Isi permintaan mencakup informasi klien (ID dan versi), status klien, dan informasi ancaman (nama daftar dan awalan hash). Untuk permintaan JSON, awalan hash harus dikirim dalam bentuk berenkode base64. Untuk mengetahui detail selengkapnya, lihat fullHashes.find isi permintaan dan penjelasan yang mengikuti contoh kode.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

Informasi klien

Kolom clientID dan clientVersion harus mengidentifikasi implementasi klien secara unik, bukan pengguna perorangan. (Informasi klien digunakan dalam logging sisi server. Anda dapat memilih nama apa pun untuk tetapi sebaiknya Anda memilih nama yang mewakili identitas asli klien, seperti nama perusahaan Anda, disajikan sebagai satu kata, dalam huruf kecil semua.)

Semua status klien

Kolom clientStates menyimpan status klien untuk semua daftar Safe Browsing di database lokal klien. (Status klien ditampilkan di kolom newClientState kolom responsthreatListUpdates.fetch.)

Daftar Safe Browsing

threatTypes, platformTypes, dan threatEntryTypes digabungkan untuk mengidentifikasi (nama) Layanan Menjelajahi daftar. Dalam 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).

Awalan hash ancaman

Array ancamanEntries berisi awalan hash dari URL yang ingin Anda periksa. Kolom hash harus berisi awalan hash yang sama persis dengan yang ada di database lokal. Sebagai misalnya, jika awalan hash lokal memiliki panjang 4 byte, panjang entri ancaman harus sepanjang 4 byte. Jika awalan hash lokal diperpanjang menjadi 7 byte, entri ancaman harus berukuran 7 byte.

Dalam contoh ini, permintaan menyertakan tiga awalan hash. Ketiga awalan tersebut akan dibandingkan dengan setiap daftar Safe Browsing untuk menentukan apakah ada hash panjang penuh yang cocok.

Catatan: Update API dan metode fullHashes.find harus selalu menggunakan kolom hash, jangan pernah menggunakan kolom URL (lihat ThreatEntry).

Respons POST HTTP

Dalam contoh berikut, respons menampilkan data yang cocok, yang disusun menurut daftar Safe Browsing, beserta durasi tunggu dan cache.

Header respons

Header respons mencakup kode status HTTP dan jenis kontennya. Klien yang menerima kode status selain HTTP/200 harus mundur (lihat Frekuensi Permintaan).

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

Isi respons

Isi respons menyertakan informasi kecocokan (nama daftar dan hash panjang penuh, metadata, jika tersedia, dan durasi cache). Dalam contoh, isi respons juga menyertakan durasi tunggu minimum. Untuk mengetahui detail selengkapnya, lihat isi respons fullHashes.find dan penjelasan yang mengikuti contoh kode.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

Kecocokan

Objek Matches menampilkan hash panjang yang cocok untuk dua awalan hash. URL yang terkait dengan {i>hash<i} ini dianggap tidak aman. Tidak ada kecocokan yang ditemukan untuk awalan {i>hash <i}ketiga, jadi tidak ada yang dikembalikan; URL yang sesuai dengan awalan {i>hash<i} ini dianggap aman.

Perhatikan bahwa contoh ini mencocokkan satu {i>hash<i} panjang penuh dengan satu awalan {i>hash<i}; mungkin saja ada beberapa {i>hash<i} lengkap yang dipetakan ke awalan {i>hash<i} yang sama.

Metadata

Kolom threatEntryMetadata bersifat opsional dan memberikan informasi tambahan tentang kecocokan ancaman. Saat ini, metadata tersedia untuk daftar Safe Browsing MALWARE/WINDOWS/URL (lihat Metadata).

Durasi cache

Kolom cacheDuration dan negativeCacheDuration menunjukkan jumlah waktu yang harus dianggap tidak aman atau aman oleh hash (lihat Cache).

Durasi tunggu minimum

Kolom minimumWaitDuration menunjukkan bahwa klien harus menunggu 300 detik (5 menit) sebelum mengirimkan permintaan {i>fullHashes<i} lainnya. Perhatikan bahwa waktu tunggu mungkin disertakan atau tidak disertakan dalam respons (lihat Frekuensi Permintaan).