Menyimpan ke cache

Dokumen ini berlaku untuk metode berikut:

• API Pencarian (v4): threatMatches.find
• Update API (v4): fullHashes.find

Tentang penyimpanan dalam cache

Untuk mengurangi penggunaan bandwidth klien dan untuk melindungi Google dari lonjakan traffic, klien dari Lookup API dan Update API diperlukan untuk membuat dan mengelola cache lokal data ancaman. Untuk Lookup API, cache digunakan untuk mengurangi jumlah threatMatches yang dikirim klien ke Google. Untuk Update API, cache digunakan untuk mengurangi jumlah fullHashes meminta yang dikirim klien ke Google. Protokol caching untuk setiap API adalah diuraikan di bawah ini.

Lookup API

Klien Lookup API harus meng-cache setiap item ThreatMatch yang ditampilkan selama durasi yang ditentukan menurut bidang cacheDuration. Klien kemudian harus melihat cache sebelum melakukan Permintaan threatMatches ke server. Jika durasi cache untuk ThreatMatch yang ditampilkan sebelumnya belum kedaluwarsa, klien harus beranggapan bahwa item masih tidak aman. Menyimpan ThreatMatch item ke dalam cache dapat mengurangi jumlah permintaan API yang dibuat oleh klien.

Contoh: ancamanMatches.find

Klik link permintaan dan respons di header tabel untuk melihat contoh lengkap.

"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]

Update API

Untuk mengurangi jumlah keseluruhan permintaan fullHashes yang dikirim ke Google menggunakan Update API, klien diperlukan untuk mempertahankan {i>cache<i} lokal. API menetapkan dua jenis caching, positif dan negatif.

Cache positif

Agar klien tidak berulang kali menanyakan status hash lengkap tertentu yang tidak aman, setiap ThreatMatch yang ditampilkan berisi durasi cache positif (didefinisikan oleh kolom cacheDuration), yang menunjukkan berapa lama {i>hash<i} lengkap akan dianggap tidak aman.

Cache negatif

Agar klien tidak berulang kali menanyakan status hash lengkap tertentu yang aman, setiap respons fullHashes menentukan durasi cache negatif untuk awalan yang diminta (ditentukan oleh kolom negativeCacheDuration). Durasi ini menunjukkan berapa lama semua {i>hash<i} penuh dengan {i>hash<i} yang diminta dianggap aman untuk daftar yang diminta, kecuali yang ditampilkan oleh server sebagai tidak aman. Cache ini sangat penting karena mencegah kelebihan traffic yang dapat disebabkan oleh tabrakan awalan {i>hash<i} dengan URL aman yang menerima banyak lalu lintas.

Mempelajari cache

Saat ingin memeriksa status URL, klien akan menghitung hash lengkapnya terlebih dahulu. Jika penuh awalan hash ada di database lokal, klien harus memeriksa cache-nya sebelum membuat permintaan fullHashes ke server.

Pertama, klien harus memeriksa apakah ditemukan cache yang positif. Jika ada cache positif yang belum habis masa berlakunya entri untuk {i>hash<i} yang lengkap, maka itu harus dianggap tidak aman. Jika entri cache positif tidak berlaku lagi, klien harus mengirimkan permintaan fullHashes untuk awalan lokal terkait. Sesuai dengan , jika server mengembalikan {i>hash<i} secara lengkap, maka hal itu dianggap tidak aman; jika tidak, dianggap aman.

Jika tidak ada entri cache positif untuk hash lengkap, klien harus memeriksa nilai negatif cache ditemukan. Jika ada entri cache negatif yang belum habis masa berlakunya untuk awalan lokal terkait, {i>hash<i} yang benar-benar lengkap dianggap aman. Jika entri cache negatif sudah tidak berlaku, atau entri tidak ada, klien harus mengirim permintaan fullHashes untuk awalan lokal yang terkait dan menafsirkan respons seperti biasa.

Memperbarui cache

Cache klien harus diperbarui setiap kali respons fullHashes diterima. Cache positif entri harus dibuat atau diperbarui untuk hash lengkap per kolom cacheDuration. Awalan hash durasi cache negatif juga harus dibuat atau diperbarui sesuai dengan negativeCacheDuration respons kolom tersebut.

Jika permintaan fullHashes berikutnya tidak menampilkan hash lengkap yang saat ini bernilai positif di-cache, maka klien tidak perlu menghapus entri cache positif. Jangan khawatir karena durasi cache positif biasanya singkat (beberapa menit) agar cepat koreksi positif palsu (PP).

Contoh skenario

Pada contoh berikut, asumsikan h(url) adalah awalan hash URL dan H(url) adalah awalan {i>hash<i} URL yang lengkap. Yaitu, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).

Sekarang, asumsikan klien (dengan cache kosong) mengunjungi example.com/ dan melihat bahwa h(example.com/) adalah dalam {i>database<i} lokal. Klien meminta hash lengkap untuk awalan hash h(example.com/) dan menerima kembali hash panjang penuh H(example.com/) bersama dengan durasi cache positif 5 dalam menit dan durasi cache negatif 1 jam.

Durasi cache positif selama 5 menit memberi tahu klien berapa lama hash panjang penuh H(example.com/) harus dianggap tidak aman tanpa mengirim permintaan fullHashes lainnya. Setelah 5 klien harus mengeluarkan permintaan fullHashes lain untuk awalan h(example.com/) tersebut jika klien mengunjungi example.com/ lagi. Klien harus mereset durasi cache negatif awalan hash sesuai dengan respons baru.

Durasi cache negatif 1 jam memberi tahu klien berapa lama semua hash lengkap lainnya selain H(example.com/) yang memiliki awalan h(example.com/) yang sama harus dianggap aman. Sebagai berdurasi 1 jam, setiap URL sedemikian rupa sehingga h(URL) = h(example.com/) harus dianggap aman, dan oleh karena itu tidak menghasilkan permintaan fullHashes (dengan asumsi bahwa H(URL) != H(example.com/)).

Jika respons fullHashes berisi nol kecocokan dan durasi cache negatif ditetapkan, maka klien tidak boleh mengeluarkan permintaan fullHashes untuk awalan apa pun yang diminta untuk durasi cache negatif.

Jika respons fullHashes berisi satu atau beberapa kecocokan, durasi cache negatif masih ditetapkan untuk seluruh respons. Dalam hal ini, durasi cache dari satu {i>hash<i} penuh menunjukkan berapa lama {i>hash <i}yang lengkap itu harus dianggap tidak aman oleh klien. Setelah cache ThreatMatch durasi berlalu, klien harus memuat ulang hash lengkap dengan mengeluarkan permintaan fullHashes untuk awalan {i>hash<i} tersebut jika URL yang diminta cocok dengan {i>hash<i} lengkap yang ada di {i>cache<i}. Di sana jika durasi cache negatif tidak berlaku. Durasi cache negatif respons hanya berlaku ke hash lengkap yang tidak ada dalam respons fullHashes. Untuk {i>hash<i} lengkap yang tidak ada dalam respons, klien tidak boleh mengeluarkan permintaan fullHashes apa pun hingga durasi cache negatif berlalu.

Contoh: fullHashes.find

Klik link permintaan dan respons di header tabel untuk melihat contoh lengkap.

"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"

"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"

"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"