Method: hashes.search

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

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

คำขอ HTTP

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

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

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

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

string (bytes format)

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

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

สตริงที่เข้ารหัสฐาน 64
filter

string

ไม่บังคับ คุณสามารถระบุเงื่อนไขนี้ได้หากไคลเอ็นต์สนใจในการกรอง เช่น การดึงข้อมูลภัยคุกคามบางประเภทเท่านั้น หากไม่ระบุ ระบบจะแสดงผลภัยคุกคามที่ตรงกันทั้งหมด เราขอแนะนำอย่างยิ่งให้ข้ามส่วนนี้ไปเพื่อให้ได้รับการปกป้องที่สมบูรณ์ที่สุดที่ Google Safe Browsing มอบให้ ดูไวยากรณ์ของนิพจน์ตัวกรองได้ที่ https://google.aip.dev/160

เนื้อหาของคำขอ

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

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

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

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

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

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

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

object (FullHash)

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

string (Duration format)

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

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

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

FullHash

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

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

string (bytes format)

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

สตริงที่เข้ารหัสฐาน 64
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 สำหรับการบังคับใช้ในเฟรมเท่านั้น