Method: hashes.search

ค้นหาแฮชแบบเต็มที่ตรงกับคำนำหน้าที่ระบุ

นี่คือวิธีที่กำหนดเองตามที่ระบุไว้ใน https://google.aip.dev/136 (วิธีที่กำหนดเองหมายถึงวิธีนี้มีชื่อที่กำหนดเองภายในคำศัพท์การพัฒนา API ทั่วไปของ Google ไม่ได้หมายถึงการใช้วิธี HTTP ที่กำหนดเอง)

คำขอ HTTP

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

URL ใช้ไวยากรณ์การแปลงรหัส gRPC

พารามิเตอร์การค้นหา

พารามิเตอร์
hashPrefixes[]

string (bytes format)

ต้องระบุ คำนำหน้าแฮชที่จะค้นหา ไคลเอ็นต์ต้องไม่ส่งคำนำหน้าแฮชเกิน 1,000 รายการ อย่างไรก็ตาม ตามขั้นตอนการประมวลผล URL แล้ว ไคลเอ็นต์ไม่ควรต้องส่งคำนำหน้าแฮชมากกว่า 30 รายการ

ปัจจุบันคำนำหน้าแฮชแต่ละรายการต้องมีความยาว 4 ไบต์พอดี ซึ่งอาจมีการผ่อนปรนในอนาคต

สตริงที่เข้ารหัส Base64

เนื้อความของคำขอ

เนื้อหาของคำขอต้องว่างเปล่า

เนื้อหาการตอบกลับ

การตอบกลับที่แสดงหลังจากค้นหาแฮชภัยคุกคาม

หากไม่พบอะไรเลย เซิร์ฟเวอร์จะแสดงสถานะ OK (รหัสสถานะ HTTP 200) โดยที่ฟิลด์ fullHashes ว่างเปล่า แทนที่จะแสดงสถานะ NOT_FOUND (รหัสสถานะ HTTP 404)

มีอะไรใหม่ใน V5: มีการแยกส่วนระหว่าง FullHash กับ FullHashDetail ในกรณีที่แฮชแสดงถึงเว็บไซต์ที่มีภัยคุกคามหลายอย่าง (เช่น ทั้งมัลแวร์และวิศวกรรมสังคม) คุณไม่จำเป็นต้องส่งแฮชแบบเต็ม 2 ครั้งเหมือนใน V4 นอกจากนี้ เรายังได้ลดความซับซ้อนของระยะเวลาแคชให้เหลือเพียงcacheDurationฟิลด์เดียว

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
ช่อง
fullHashes[]

object (FullHash)

รายการที่ไม่เรียงลำดับ รายการแฮชแบบเต็มที่พบโดยไม่มีการเรียงลำดับ
cacheDuration

string (Duration format)

ระยะเวลาแคชฝั่งไคลเอ็นต์ ไคลเอ็นต์ต้องเพิ่มระยะเวลานี้ลงในเวลาปัจจุบันเพื่อกำหนดเวลาหมดอายุ จากนั้นเวลาหมดอายุจะมีผลกับคำนำหน้าแฮชทุกรายการที่ไคลเอ็นต์ค้นหาในคำขอ ไม่ว่าระบบจะส่งแฮชแบบเต็มกี่รายการในการตอบกลับก็ตาม แม้ว่าเซิร์ฟเวอร์จะไม่แสดงแฮชแบบเต็มสำหรับคำนำหน้าแฮชที่เฉพาะเจาะจง แต่ไคลเอ็นต์ก็ต้องแคชข้อเท็จจริงนี้ด้วย

หากฟิลด์ fullHashes ว่างเปล่าเท่านั้น ไคลเอ็นต์อาจเพิ่ม cacheDuration เพื่อกำหนดวันหมดอายุใหม่ที่หลังจากวันที่เซิร์ฟเวอร์ระบุ ไม่ว่าในกรณีใดก็ตาม ระยะเวลาแคชที่เพิ่มขึ้นต้องไม่เกิน 24 ชั่วโมง

สำคัญ: ไคลเอ็นต์ต้องไม่ถือว่าเซิร์ฟเวอร์จะแสดงระยะเวลาแคชเดียวกันสำหรับการตอบกลับทั้งหมด เซิร์ฟเวอร์อาจเลือกระยะเวลาแคชที่แตกต่างกันสำหรับการตอบกลับที่แตกต่างกันได้ ทั้งนี้ขึ้นอยู่กับสถานการณ์

ระยะเวลาเป็นวินาทีที่มีเศษทศนิยมได้สูงสุด 9 หลัก โดยลงท้ายด้วย "s" เช่น "3.5s"

FullHash

แฮชแบบเต็มที่ระบุว่าตรงกันอย่างน้อย 1 รายการ

การแสดง JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
ช่อง
fullHash

string (bytes format)

แฮชแบบเต็มที่ตรงกัน นี่คือแฮช SHA256 โดยจะมีความยาว 32 ไบต์

สตริงที่เข้ารหัส Base64
fullHashDetails[]

object (FullHashDetail)

รายการที่ไม่เรียงลำดับ ฟิลด์ที่ซ้ำกันซึ่งระบุรายละเอียดที่เกี่ยวข้องกับแฮชแบบเต็มนี้

FullHashDetail

รายละเอียดเกี่ยวกับแฮชแบบเต็มที่ตรงกัน

หมายเหตุสำคัญเกี่ยวกับความเข้ากันได้แบบย้อนกลับ: เซิร์ฟเวอร์อาจเพิ่มประเภทภัยคุกคามและแอตทริบิวต์ของภัยคุกคามใหม่ได้ทุกเมื่อ การเพิ่มดังกล่าวถือเป็นการเปลี่ยนแปลงเวอร์ชันย่อย นโยบายของ Google คือไม่แสดงหมายเลขเวอร์ชันย่อยใน API (ดูนโยบายการกำหนดเวอร์ชันได้ที่ https://cloud.google.com/apis/design/versioning) ดังนั้นไคลเอ็นต์จึงต้องเตรียมพร้อมที่จะรับข้อความ FullHashDetail ที่มีค่า enum ThreatType หรือค่า enum ThreatAttribute ที่ไคลเอ็นต์ถือว่าไม่ถูกต้อง ดังนั้น ไคลเอ็นต์จึงมีหน้าที่ตรวจสอบความถูกต้องของค่า enum ทั้งหมดของ ThreatType และ ThreatAttribute หากค่าใดถือว่าไม่ถูกต้อง ไคลเอ็นต์ต้องไม่สนใจข้อความ FullHashDetail ทั้งหมด

การแสดง JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
ช่อง
threatType

enum (ThreatType)

ประเภทภัยคุกคาม ช่องนี้จะไม่มีวันว่าง
attributes[]

enum (ThreatAttribute)

รายการที่ไม่เรียงลำดับ แอตทริบิวต์เพิ่มเติมเกี่ยวกับแฮชแบบเต็มเหล่านั้น ซึ่งอาจเป็นค่าว่าง

ThreatAttribute

คุณลักษณะของภัยคุกคาม แอตทริบิวต์เหล่านี้อาจให้ความหมายเพิ่มเติมแก่ภัยคุกคามหนึ่งๆ แต่จะไม่มีผลต่อประเภทภัยคุกคาม เช่น แอตทริบิวต์หนึ่งอาจระบุความเชื่อมั่นต่ำ ขณะที่อีกแอตทริบิวต์หนึ่งอาจระบุความเชื่อมั่นสูง ทั้งนี้อาจมีการเพิ่มแอตทริบิวต์อื่นๆ ในอนาคต

Enum
THREAT_ATTRIBUTE_UNSPECIFIED แอตทริบิวต์ที่ไม่รู้จัก หากเซิร์ฟเวอร์ส่งคืนค่านี้ ไคลเอ็นต์จะไม่สนใจ FullHashDetail ทั้งหมด
CANARY ระบุว่าไม่ควรใช้ threatType ในการบังคับใช้
FRAME_ONLY ระบุว่าควรใช้ threatType สำหรับการบังคับใช้กับเฟรมเท่านั้น