API การอัปเดต Safe Browsing (v4)

ภาพรวม

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

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

การอัปเดตฐานข้อมูลในเครื่อง

ลูกค้าต้องอัปเดตรายการ Google Safe Browsing ในฐานข้อมูลของเครื่องเป็นระยะเพื่อให้เป็นปัจจุบันอยู่เสมอ เพื่อประหยัดแบนด์วิดท์ ไคลเอ็นต์จะดาวน์โหลดคำนำหน้าแฮชของ URL แทน URL ดิบ เช่น หาก "www.badurl.com/" อยู่ในรายการ Google Safe Browsing ไคลเอ็นต์จะดาวน์โหลดคำนำหน้าแฮช SHA256 ของ URL นั้น ไม่ใช่ URL นั้นๆ ในกรณีส่วนใหญ่ คำนำหน้าแฮชจะมีความยาว 4 ไบต์ ซึ่งหมายความว่าต้นทุนแบนด์วิดท์เฉลี่ยของการดาวน์โหลดรายการเดียวในรายการหนึ่งคือ 4 ไบต์ก่อนการบีบอัด

หากต้องการอัปเดตรายการ Google Safe Browsing ในฐานข้อมูลภายใน ให้ส่งคำขอ HTTP POST ไปยังเมธอด threatListUpdates.fetch

  • คำขอ HTTP POST มีชื่อรายการที่จะอัปเดตพร้อมข้อจำกัดต่างๆ ของไคลเอ็นต์เพื่อพิจารณาข้อจำกัดด้านหน่วยความจำและแบนด์วิดท์
  • การตอบกลับ HTTP POST จะแสดงการอัปเดตแบบเต็มหรือการอัปเดตบางส่วน การตอบกลับอาจแสดงระยะเวลารอขั้นต่ำด้วย

ตัวอย่าง: ThreatListUpdates.fetch

คำขอ HTTP POST

ในตัวอย่างต่อไปนี้ จะมีการขอการอัปเดตสำหรับรายการ Google Safe Browsing รายการเดียว

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

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

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

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

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

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}
ข้อมูลไคลเอ็นต์

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

รายการ Google Safe Browsing

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

สถานะไคลเอ็นต์

ช่อง state เก็บสถานะปัจจุบันของไคลเอ็นต์ของรายการ Google Safe Browsing (สถานะไคลเอ็นต์จะแสดงในช่อง newClientState ของการตอบสนอง threatListUpdates.fetch) สำหรับการอัปเดตเบื้องต้น ให้เว้นช่อง state ว่างไว้

ข้อจำกัดด้านขนาด

ช่อง maxUpdateEntries จะระบุจำนวนการอัปเดตทั้งหมดที่ลูกค้าจัดการได้ (ในตัวอย่าง 2048) ช่อง maxDatabaseEntries จะระบุจำนวนรายการทั้งหมดที่ฐานข้อมูลท้องถิ่นจัดการได้ (ในตัวอย่างนี้คือ 4096) ไคลเอ็นต์ควรกำหนดข้อจำกัดด้านขนาดไว้เพื่อปกป้องข้อจำกัดด้านหน่วยความจำและแบนด์วิดท์ ตลอดจนป้องกันการเพิ่มจำนวนรายการ ดูข้อมูลเพิ่มเติมได้ที่อัปเดตข้อจำกัด)

การบีบอัดที่รองรับ

ช่อง supportedCompressions จะแสดงประเภทการบีบอัดที่ไคลเอ็นต์รองรับ ในตัวอย่างนี้ ไคลเอ็นต์รองรับเฉพาะข้อมูลดิบที่ไม่ได้บีบอัด อย่างไรก็ตาม Google Safe Browsing รองรับประเภทการบีบอัดอื่นๆ เพิ่มเติม (ดูการบีบอัด)

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

ในตัวอย่างนี้ การตอบกลับจะแสดงการอัปเดตบางส่วนสำหรับรายการ Google Safe Browsing โดยใช้ประเภทการบีบอัดที่ขอ

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

ส่วนหัวการตอบกลับมีรหัสสถานะ HTTP และประเภทเนื้อหา ไคลเอ็นต์ที่ได้รับรหัสสถานะอื่นที่ไม่ใช่ HTTP/200 ต้องเข้าสู่โหมดย้อนกลับ (โปรดดูความถี่ในการส่งคำขอ)

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

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

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

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}
การอัปเดตฐานข้อมูล

ฟิลด์ responseType จะระบุการอัปเดตบางส่วนหรือทั้งหมด ในตัวอย่าง ระบบจะส่งการอัปเดตบางส่วนกลับมา ดังนั้นการตอบกลับจะมีทั้งการเพิ่มและการนำออก โดยอาจมีการเพิ่มหลายชุด แต่นำออกเพียงชุดเดียว (ดูการอัปเดตฐานข้อมูล)

สถานะลูกค้าใหม่

ช่อง newClientState เก็บสถานะไคลเอ็นต์ใหม่สำหรับรายการ Google Safe Browsing ที่อัปเดตใหม่ ไคลเอ็นต์ต้องบันทึกสถานะไคลเอ็นต์ใหม่สำหรับคำขออัปเดตครั้งต่อๆ ไป (ช่อง state ในคำขอ threatListUpdates.fetch หรือช่อง clientStates ในคำขอfullHashes.find)

การตรวจสอบข้อผิดพลาด

Checksum จะช่วยให้ไคลเอ็นต์ยืนยันว่าฐานข้อมูลในเครื่องไม่มีความเสียหายใดๆ หาก การตรวจสอบข้อผิดพลาดไม่ตรงกัน ไคลเอ็นต์ต้องล้างฐานข้อมูลและออกการอัปเดตใหม่โดยมีช่อง state ที่ว่างเปล่า อย่างไรก็ตาม ลูกค้าที่อยู่ในสถานการณ์นี้ยังคงต้องปฏิบัติตามช่วงเวลาเพื่ออัปเดต (ดูความถี่ในการส่งคำขอ)

ระยะเวลารอขั้นต่ำ

ช่อง minimumWaitDuration ระบุว่าไคลเอ็นต์ต้องรอ 593.44 วินาที (9.89 นาที) ก่อนที่จะส่งคำขออัปเดตอีกครั้ง โปรดทราบว่าระยะเวลารออาจรวมหรือไม่รวมอยู่ในการตอบกลับก็ได้ (ดูความถี่ในการส่งคำขอ)

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

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

หากมีคำนำหน้าแฮชในฐานข้อมูลในเครื่อง (ความขัดแย้งของคำนำหน้าแฮช) ไคลเอ็นต์ต้องส่งคำนำหน้าแฮชไปยังเซิร์ฟเวอร์ Google Safe Browsing เพื่อการยืนยัน เซิร์ฟเวอร์จะแสดงผลแฮช SHA 256 แบบความยาวเต็มทั้งหมดที่มีคำนำหน้าแฮชที่ระบุ หากแฮชแบบความยาวเต็มรายการใดรายการหนึ่งตรงกับแฮชแบบเต็มของ URL ที่เป็นปัญหา ระบบจะถือว่า URL นั้นไม่ปลอดภัย หากไม่มีแฮชแบบเต็มที่ตรงกับแฮชแบบความยาวเต็มของ URL ที่เป็นปัญหา ระบบจะถือว่า URL นั้นปลอดภัย

Google จะไม่ทราบเกี่ยวกับ URL ที่คุณตรวจสอบไม่ว่าในขั้นตอนใด Google จะเรียนรู้คำนำหน้าแฮชของ URL แต่คำนำหน้าแฮชไม่ได้ให้ข้อมูลเกี่ยวกับ URL จริงไว้มากนัก

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

  • คำขอ HTTP POST มีรายการภัยคุกคามได้สูงสุด 500 รายการ
  • คำขอ HTTP POST มีคำนำหน้าแฮชของ URL ที่จะตรวจสอบ ขอแนะนำให้ไคลเอ็นต์รวมรายการภัยคุกคามหลายรายการไว้ในคำขอเดียวเพื่อลดการใช้แบนด์วิดท์
  • การตอบกลับ HTTP POST จะแสดงผลแฮชแบบเต็มที่ตรงกันพร้อมระยะเวลาของแคชเชิงบวกและเชิงลบ การตอบกลับอาจแสดงระยะเวลารอขั้นต่ำด้วย

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

คำขอ HTTP POST

ในตัวอย่างต่อไปนี้ ระบบจะส่งชื่อรายการ Google Safe Browsing 2 รายการและคำนำหน้าแฮช 3 รายการเพื่อเปรียบเทียบและการยืนยัน

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

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

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

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

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

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}
ข้อมูลไคลเอ็นต์

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

สถานะของลูกค้าทั้งหมด

ช่อง clientStates เก็บสถานะไคลเอ็นต์สำหรับรายการ Google Safe Browsing ทั้งหมดในฐานข้อมูลภายในของลูกค้า (สถานะไคลเอ็นต์จะแสดงในช่อง newClientState ของการตอบสนอง threatListUpdates.fetch)

รายการ Google Safe Browsing

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

คำนำหน้าแฮชภัยคุกคาม

อาร์เรย์ ThreatEntries มีคำนำหน้าแฮชของ URL ที่คุณต้องการตรวจสอบ ช่อง hash ต้องมีคำนำหน้าแฮชที่ตรงกับในฐานข้อมูลของเครื่อง เช่น หากคำนำหน้าแฮชในเครื่องยาว 4 ไบต์ รายการภัยคุกคามต้องยาว 4 ไบต์ หากคำนำหน้าแฮชในเครื่องยาวถึง 7 ไบต์ รายการภัยคุกคามต้องมีความยาว 7 ไบต์

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

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

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

ในตัวอย่างต่อไปนี้ การตอบกลับจะแสดงข้อมูลที่ตรงกัน ซึ่งจัดระเบียบโดยรายการ Google Safe Browsing พร้อมแคชและระยะเวลารอ

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

ส่วนหัวการตอบกลับมีรหัสสถานะ HTTP และประเภทเนื้อหา ไคลเอ็นต์ที่ได้รับรหัสสถานะอื่นนอกเหนือจาก HTTP/200 ต้องย้อนกลับ (ดูความถี่ของคำขอ)

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

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

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

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}
ตรงกับ

ออบเจ็กต์ "การจับคู่" จะแสดงผลแฮชความยาวเต็มที่ตรงกันสําหรับคํานําหน้าแฮช 2 คํา URL ที่สอดคล้องกับแฮชเหล่านี้จะถือว่าไม่ปลอดภัย ไม่พบรายการที่ตรงกันสำหรับคำนำหน้าแฮชที่ 3 จึงไม่แสดงผลใดๆ และถือว่า URL ที่ตรงกับคำนำหน้าแฮชนี้ปลอดภัย

โปรดทราบว่าตัวอย่างนี้จับคู่แฮชแบบเต็ม 1 รายการกับค่านำหน้าแฮช 1 รายการ อย่างไรก็ตาม อาจมีแฮชแบบเต็มหลายรายการที่แมปกับคํานําหน้าแฮชเดียวกัน

Metadata

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

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

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

ระยะเวลารอขั้นต่ำ

ช่อง minimumWaitDuration ระบุว่าไคลเอ็นต์ต้องรอ 300 วินาที (5 นาที) ก่อนที่จะส่งคำขอ FullHash อีกรายการ โปรดทราบว่าระยะเวลารออาจรวมหรือไม่รวมอยู่ในการตอบกลับก็ได้ (ดูความถี่ในการส่งคำขอ)