Safe Browsing Lookup API (v4)

ภาพรวม

Lookup API ช่วยให้แอปพลิเคชันไคลเอ็นต์ส่งคำขอไปยังเซิร์ฟเวอร์ Google Safe Browsing เพื่อตรวจสอบว่ามีการรวม URL ไว้ในรายการ Google Safe Browsing หรือไม่ หากพบ URL ในรายการอย่างน้อย 1 รายการ ระบบจะแสดงข้อมูลที่ตรงกัน

กำลังตรวจสอบ URL

หากต้องการตรวจสอบว่า URL อยู่ในรายการ Google Safe Browsing หรือไม่ ให้ส่งคำขอ HTTP POST ไปยังเมธอด threatMatches.find ดังนี้

• คำขอ HTTP POST มี URL ได้สูงสุด 500 รายการ URL ต้องเป็น URL ที่ถูกต้อง (ดู RFC 2396) แต่ไม่จำเป็นต้องกำหนดหน้า Canonical หรือเข้ารหัส
• การตอบกลับ HTTP POST จะแสดงผล URL ที่ตรงกันพร้อมกับระยะเวลาของแคช

ตัวอย่าง: ThreatMatches.find

คำขอ HTTP POST

ในตัวอย่างต่อไปนี้ จะมีการส่งรายการ Google Safe Browsing 2 รายการและ URL 3 รายการไปยังเซิร์ฟเวอร์เพื่อระบุว่ามีข้อมูลที่ตรงกันหรือไม่

ส่วนหัวของคำขอ

ส่วนหัวของคำขอจะมี URL คำขอและประเภทเนื้อหา อย่าลืมแทนที่คีย์ API สำหรับ API_KEY ใน URL

  POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1
  Content-Type: application/json
  

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

เนื้อหาของคำขอประกอบด้วยข้อมูลไคลเอ็นต์ (รหัสและเวอร์ชัน) และข้อมูลภัยคุกคาม (ชื่อและ URL ในรายการ) ดูรายละเอียดเพิ่มเติมได้ที่เนื้อหาคำขอ threatMatches.find และคำอธิบายตามตัวอย่างโค้ด

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

ข้อมูลไคลเอ็นต์

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

รายการ Google Safe Browsing

ช่อง threatType, platformType และ threatEntryType รวมกันเพื่อระบุ (ชื่อ) รายการของ Google Safe Browsing ในตัวอย่าง มีการระบุ 2 รายการ: MALWARE/WINDOWS/URL และ SOCIAL_ENGINEERING/WINDOWS/URL ก่อนที่จะส่งคำขอ โปรดตรวจสอบว่าประเภทชุดค่าผสมที่คุณระบุถูกต้อง (ดูรายการ Google Safe Browsing)

URL ภัยคุกคาม

ในตัวอย่างนี้ อาร์เรย์ threatEntries มี URL 3 รายการ (urltocheck1.org, urltocheck2.org และ urltocheck3.org) ซึ่งจะตรวจสอบกับรายการ Google Safe Browsing 2 รายการ

หมายเหตุ: Lookup API และเมธอด threatMatches ควรใช้ช่อง URL เสมอ ไม่ใช่ช่อง hash (ดู ThreatEntry)

การตอบกลับ HTTP POST

ในตัวอย่างต่อไปนี้ การตอบกลับจะแสดงผลการจับคู่ โดย URL 2 จาก 3 รายการที่ระบุในคำขอจะอยู่ใน 1 ใน 2 รายการของ Google Safe Browsing ที่ระบุในคำขอ

ส่วนหัวการตอบกลับ

ส่วนหัวการตอบกลับมีรหัสสถานะ HTTP และประเภทเนื้อหา

HTTP/1.1 200 OK
Content-Type: application/json

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

เนื้อหาการตอบกลับจะมีข้อมูลการจับคู่ (ชื่อรายการและ URL ที่พบในรายการเหล่านั้น ข้อมูลเมตา หากมี และระยะเวลาของแคช) ดูรายละเอียดเพิ่มเติมได้ที่เนื้อหาการตอบกลับ threatMatches.find และคำอธิบายตามตัวอย่างโค้ด

หมายเหตุ: หากไม่มีรายการที่ตรงกัน (กล่าวคือ หากไม่พบ ไม่มี URL ที่ระบุในคำขอในรายการใดก็ตามที่ระบุในคำขอ) การตอบกลับ HTTP POST จะแสดงออบเจ็กต์ที่ว่างเปล่าในเนื้อหาการตอบกลับ

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

ตรงกับ

ออบเจ็กต์ matches แสดงรายชื่อของ Google Safe Browsing และ URL หากตรงกัน ในตัวอย่าง พบ URL 2 รายการ (urltocheck1.org และ urltocheck2.org) ในรายการ Google Safe Browsing (MALWARE/WINDOWS/URL) จึงแสดงผลข้อมูลที่ตรงกัน ไม่พบ URL ที่สาม (urltocheck3.org) ในทั้งสองรายการ ดังนั้นจะไม่มีการส่งกลับข้อมูลสำหรับ URL นี้

Metadata

ช่อง threatEntryMetadata เป็นช่องที่ไม่บังคับและให้ข้อมูลเพิ่มเติมเกี่ยวกับภัยคุกคามที่ตรงกัน ปัจจุบันข้อมูลเมตาพร้อมใช้งานสำหรับรายการ Google Safe Browsing ของ MALWARE/WINDOWS/URL (ดูข้อมูลเมตา)

ระยะเวลาของแคช

ช่อง cacheDuration ระบุระยะเวลาที่ต้องถือว่า URL ดังกล่าวไม่ปลอดภัย (ดูการแคช)