Safe Browsing Lookup API (v4)

ภาพรวม

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

การตรวจสอบ URL

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

• คำขอ HTTP POST มี URL ได้สูงสุด 500 รายการ 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 จะถูกรวมเข้าด้วยกันเพื่อระบุ (ชื่อ) รายการ 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

ในตัวอย่างต่อไปนี้ การตอบกลับจะแสดงค่าที่ตรงกัน 2 จาก 3 URL ที่ระบุไว้ในส่วน พบคำขอใน 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 สองแห่ง (urltocheck1.org และ urltocheck2.org) ที่หนึ่งใน รายการ Google Safe Browsing (มัลแวร์/WINDOWS/URL) เพื่อแสดงข้อมูลที่ตรงกัน URL ที่ 3 ไม่พบ (urltocheck3.org) ในทั้ง 2 รายการ จึงไม่มีข้อมูลแสดงผลสำหรับ URL นี้

ข้อมูลเมตา

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

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

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