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

ภาพรวม

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

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

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

ไคลเอ็นต์ต้องอัปเดตรายการการท่องเว็บปลอดภัยในฐานข้อมูลในเครื่องเป็นระยะๆ เพื่อให้ข้อมูลเป็นปัจจุบัน ลูกค้าจะดาวน์โหลดคำนำหน้าแฮชของ URL แทน URL ดิบเพื่อประหยัดแบนด์วิดท์ เช่น หาก "www.badurl.com/" อยู่ในรายการการท่องเว็บอย่างปลอดภัย ลูกค้าจะดาวน์โหลดคำนำหน้าแฮช 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 ในตัวอย่างนี้จะระบุ 1 รายการ มัลแวร์/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

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

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

{
  "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 request หรือช่อง clientStates ในฟิลด์ คำขอfullHashes.find)

Checksum

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

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

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

การตรวจสอบ URL

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

หากมีคำนำหน้าแฮชอยู่ในฐานข้อมูลในเครื่อง (คำนำหน้าแฮชทับซ้อนกัน) ลูกค้าต้องส่งคำนำหน้าแฮชไปยังเซิร์ฟเวอร์ของ 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_KEY ใน URL ด้วยคีย์ API ของคุณ

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"
}

การจับคู่

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

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

ข้อมูลเมตา

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

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

ฟิลด์ cacheDuration และ negativeCacheDuration จะระบุจำนวนเงิน ต้องแฮช พิจารณาว่าไม่ปลอดภัยหรือปลอดภัย (ดูการแคช)

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

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