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 ได้รับการปกป้องอย่างสมบูรณ์ที่สุด

มีการระบุตัวกรองโดยใช้ Google Common Expression Language ซึ่งดูได้ที่ https://github.com/google/cel-spec พร้อมด้วยตัวอย่างทั่วไป ตัวอย่างเฉพาะเจาะจงที่ใช้ได้ที่นี่

ตัวกรอง "threatType == ThreatType.SOCIAL_ENGINEERING" กำหนดให้ภายใน FullHashDetail ประเภทภัยคุกคามต้องเป็น SOCIAL_ENGINEERING ตัวระบุ "threatType" หมายถึงประเภทภัยคุกคามในปัจจุบัน ตัวระบุ "ThreatType" หมายถึงการรวบรวมภัยคุกคามประเภทที่เป็นไปได้ทั้งหมด

ตัวกรอง "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" กำหนดว่าประเภทภัยคุกคามต้องเป็น UNWANTED_SOFTWARE หรือ MALWARE

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

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

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

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

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

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

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