Method: hashes.search

Menelusuri hash lengkap yang cocok dengan awalan yang ditentukan.

Ini adalah metode kustom seperti yang ditentukan oleh https://google.aip.dev/136 (metode kustom mengacu pada metode ini yang memiliki nama kustom dalam nomenklatur pengembangan API umum Google; metode ini tidak mengacu pada penggunaan metode HTTP kustom).

Permintaan HTTP

GET https://safebrowsing.googleapis.com/v5/hashes:search

URL ini menggunakan sintaksis gRPC Transcoding.

Parameter kueri

Parameter
hashPrefixes[]

string (bytes format)

Wajib. Awalan hash yang akan dicari. Klien TIDAK BOLEH mengirim lebih dari 1.000 awalan hash. Namun, setelah prosedur pemrosesan URL, klien SEBAIKNYA TIDAK perlu mengirim lebih dari 30 awalan hash.

Saat ini, setiap awalan hash harus memiliki panjang tepat 4 byte. Hal ini MUNGKIN tidak terlalu ketat pada masa mendatang.

String berenkode base64.

Isi permintaan

Isi permintaan harus kosong.

Isi respons

Respons yang ditampilkan setelah menelusuri hash ancaman.

Jika tidak ada yang ditemukan, server akan menampilkan status OK (kode status HTTP 200) dengan kolom fullHashes kosong, bukan menampilkan status NOT_FOUND (kode status HTTP 404).

Yang baru di V5: Ada pemisahan antara FullHash dan FullHashDetail. Jika hash merepresentasikan situs yang memiliki beberapa ancaman (misalnya, MALWARE dan SOCIAL_ENGINEERING), hash lengkap tidak perlu dikirim dua kali seperti pada V4. Selain itu, durasi cache telah disederhanakan menjadi satu kolom cacheDuration.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Kolom
fullHashes[]

object (FullHash)

Daftar yang tidak diurutkan. Daftar lengkap hash yang tidak diurutkan yang ditemukan.
cacheDuration

string (Duration format)

Durasi cache sisi klien. Klien HARUS menambahkan durasi ini ke waktu saat ini untuk menentukan waktu habis masa berlaku. Waktu habis masa berlaku kemudian berlaku untuk setiap awalan hash yang dikueri oleh klien dalam permintaan, terlepas dari jumlah hash lengkap yang ditampilkan dalam respons. Meskipun server tidak menampilkan hash lengkap untuk awalan hash tertentu, informasi ini JUGA HARUS di-cache oleh klien.

Jika dan hanya jika kolom fullHashes kosong, klien DAPAT meningkatkan cacheDuration untuk menentukan masa berlaku baru yang lebih lama daripada yang ditentukan oleh server. Bagaimanapun, durasi cache yang ditingkatkan tidak boleh lebih dari 24 jam.

Penting: klien TIDAK BOLEH mengasumsikan bahwa server akan menampilkan durasi cache yang sama untuk semua respons. Server DAPAT memilih durasi cache yang berbeda untuk respons yang berbeda, bergantung pada situasinya.

Durasi dalam detik dengan maksimal sembilan digit pecahan, yang diakhiri dengan 's'. Contoh: "3.5s".

FullHash

Hash lengkap diidentifikasi dengan satu atau beberapa kecocokan.

Representasi JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Kolom
fullHash

string (bytes format)

Hash lengkap yang cocok. Ini adalah hash SHA256. Panjangnya akan tepat 32 byte.

String berenkode base64.
fullHashDetails[]

object (FullHashDetail)

Daftar yang tidak diurutkan. Kolom berulang yang mengidentifikasi detail yang relevan dengan hash lengkap ini.

FullHashDetail

Detail tentang hash penuh yang cocok.

Catatan penting tentang kompatibilitas ke depan: jenis ancaman dan atribut ancaman baru dapat ditambahkan oleh server kapan saja; penambahan tersebut dianggap sebagai perubahan versi kecil. Kebijakan Google adalah tidak mengekspos nomor versi minor di API (lihat https://cloud.google.com/apis/design/versioning untuk kebijakan pembuatan versi), sehingga klien HARUS siap menerima pesan FullHashDetail yang berisi nilai enum ThreatType atau nilai enum ThreatAttribute yang dianggap tidak valid oleh klien. Oleh karena itu, klien bertanggung jawab untuk memeriksa validitas semua nilai enum ThreatType dan ThreatAttribute; jika ada nilai yang dianggap tidak valid, klien HARUS mengabaikan seluruh pesan FullHashDetail.

Representasi JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Kolom
threatType

enum (ThreatType)

Jenis ancaman. Kolom ini tidak akan pernah kosong.
attributes[]

enum (ThreatAttribute)

Daftar yang tidak diurutkan. Atribut tambahan tentang hash lengkap tersebut. Kolom ini mungkin kosong.

ThreatAttribute

Atribut ancaman. Atribut ini dapat memberikan makna tambahan pada ancaman tertentu, tetapi tidak akan memengaruhi jenis ancaman. Misalnya, satu atribut dapat menentukan keyakinan yang lebih rendah, sementara atribut lain dapat menentukan keyakinan yang lebih tinggi. Atribut lainnya dapat ditambahkan pada masa mendatang.

Enum
THREAT_ATTRIBUTE_UNSPECIFIED Atribut tidak diketahui. Jika ditampilkan oleh server, klien akan mengabaikan FullHashDetail yang melampirinya.
CANARY Menunjukkan bahwa threatType tidak boleh digunakan untuk penegakan.
FRAME_ONLY Menunjukkan bahwa threatType hanya boleh digunakan untuk penegakan pada frame.