Migration From V4
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
การปรับปรุงที่สำคัญอย่างหนึ่งของ Google Safe Browsing v5 เมื่อเทียบกับ v4 (โดยเฉพาะ v4 Update API) คือความใหม่และความครอบคลุมของข้อมูล เนื่องจากการป้องกันขึ้นอยู่กับฐานข้อมูลในเครื่องที่ไคลเอ็นต์ดูแลเป็นอย่างมาก ความล่าช้าและขนาดของการอัปเดตฐานข้อมูลในเครื่องจึงเป็นสาเหตุหลักที่ทำให้พลาดการป้องกัน ใน v4 ไคลเอ็นต์ทั่วไปจะใช้เวลา 20-50 นาทีในการรับรายการภัยคุกคามเวอร์ชันล่าสุด น่าเสียดายที่การโจมตีแบบฟิชชิงแพร่กระจายอย่างรวดเร็ว โดยในปี 2021 เว็บไซต์ 60% ที่ทำการโจมตีมีอายุการใช้งานน้อยกว่า 10 นาที การวิเคราะห์ของเราแสดงให้เห็นว่าการป้องกันฟิชชิงที่ขาดหายไปประมาณ 25-30% เกิดจากข้อมูลที่ล้าสมัยดังกล่าว นอกจากนี้ อุปกรณ์บางเครื่องยังไม่มีความพร้อมในการจัดการรายการภัยคุกคามทั้งหมดของ Google Safe Browsing ซึ่งมีขนาดใหญ่ขึ้นเรื่อยๆ เมื่อเวลาผ่านไป
หากปัจจุบันคุณใช้ v4 Update API คุณจะย้ายข้อมูลจาก v4 ไปยัง v5 ได้อย่างราบรื่นโดยไม่ต้องรีเซ็ตหรือลบฐานข้อมูลในเครื่อง ส่วนนี้จะอธิบายวิธีดำเนินการดังกล่าว
การแปลงการอัปเดตรายการ
ใน v5 ระบบจะระบุรายการตามชื่อเท่านั้น ซึ่งต่างจาก v4 ที่ระบุรายการตามทูเพิลของประเภทภัยคุกคาม ประเภทแพลตฟอร์ม ประเภทรายการภัยคุกคาม ซึ่งจะช่วยให้มีความยืดหยุ่นเมื่อรายการ v5 หลายรายการแชร์ภัยคุกคามประเภทเดียวกันได้ ระบบจะนำประเภทแพลตฟอร์มและประเภทรายการภัยคุกคามออกใน v5
ใน v4 ผู้ใช้จะใช้เมธอด threatListUpdates.fetch เพื่อดาวน์โหลดรายการ ใน v5 คุณจะต้องเปลี่ยนไปใช้เมธอด hashLists.batchGet
ควรทำการเปลี่ยนแปลงต่อไปนี้ในคำขอ
- นำออบเจ็กต์ v4
ClientInfo ออกทั้งหมด แทนที่จะระบุการระบุตัวตนของไคลเอ็นต์โดยใช้ช่องเฉพาะ ให้ใช้ส่วนหัว User-Agent ที่รู้จักกันดี แม้ว่าจะไม่มีรูปแบบที่กำหนดไว้สำหรับการระบุไคลเอ็นต์ในส่วนหัวนี้ แต่เราขอแนะนำให้ระบุรหัสไคลเอ็นต์และเวอร์ชันไคลเอ็นต์เดิมโดยคั่นด้วยอักขระช่องว่างหรือเครื่องหมายทับ
- สำหรับออบเจ็กต์ v4
ListUpdateRequest แต่ละรายการ ให้ทำดังนี้
- ค้นหาชื่อรายการ v5 ที่เกี่ยวข้องจากรายการที่พร้อมใช้งาน แล้วระบุชื่อนั้นในคำขอ v5
- นำฟิลด์ที่ไม่จำเป็นออก เช่น
threat_entry_type หรือ platform_type
- ฟิลด์
state ใน v4 ใช้กับฟิลด์ versions ใน v5 ได้โดยตรง คุณสามารถส่งสตริงไบต์เดียวกันกับที่จะส่งไปยังเซิร์ฟเวอร์โดยใช้ฟิลด์ state ใน v4 ใน v5 ได้โดยใช้ฟิลด์ versions
- สำหรับข้อจำกัด v4 นั้น v5 จะใช้เวอร์ชันที่เรียบง่ายกว่าที่เรียกว่า
SizeConstraints ไม่ควรใส่ช่องเพิ่มเติม เช่น region
ควรทำการเปลี่ยนแปลงต่อไปนี้กับการตอบกลับ
- enum
ResponseType ของ v4 จะแทนที่ด้วยช่องบูลีนชื่อ partial_update
- ตอนนี้ช่อง
minimum_wait_duration สามารถเป็น 0 หรือเว้นว่างได้ หากเป็นเช่นนั้น ระบบจะขอให้ไคลเอ็นต์ส่งคำขออื่นทันที กรณีนี้จะเกิดขึ้นก็ต่อเมื่อไคลเอ็นต์ระบุข้อจำกัดที่เล็กลงเกี่ยวกับขนาดการอัปเดตสูงสุดใน SizeConstraints มากกว่าขนาดฐานข้อมูลสูงสุด
- คุณจะต้องปรับอัลกอริทึมการถอดรหัสของ Rice สำหรับจำนวนเต็ม 32 บิต ความแตกต่างคือข้อมูลที่เข้ารหัสจะเข้ารหัสด้วยเอนเดียนเนสที่แตกต่างกัน ทั้งใน v4 และ v5 ระบบจะจัดเรียงคำนำหน้าแฮชแบบ 32 บิตตามลำดับพจนานุกรม แต่ใน v4 ระบบจะถือว่าคำนำหน้าเหล่านั้นเป็นแบบ Little Endian เมื่อจัดเรียง ในขณะที่ใน v5 ระบบจะถือว่าคำนำหน้าเหล่านั้นเป็นแบบ Big Endian เมื่อจัดเรียง ซึ่งหมายความว่าไคลเอ็นต์ไม่จำเป็นต้องทำการจัดเรียงใดๆ เนื่องจาก Lexicographic Sorting เหมือนกับการจัดเรียงตัวเลขที่มี Big Endian ดูตัวอย่างการเรียงลำดับนี้ในการติดตั้งใช้งาน v4 ของ Chromium ได้ที่นี่ คุณนำการจัดเรียงดังกล่าวออกได้
- คุณจะต้องใช้อัลกอริทึมการถอดรหัส Rice สำหรับความยาวแฮชอื่นๆ ด้วย
การแปลงการค้นหาแฮช
ใน v4 ผู้ใช้จะใช้เมธอด fullHashes.find เพื่อรับแฮชแบบเต็ม ส่วนใน v5 จะเทียบเท่ากับเมธอด hashes.search
ควรทำการเปลี่ยนแปลงต่อไปนี้ในคำขอ
- จัดโครงสร้างโค้ดให้ส่งเฉพาะคำนำหน้าแฮชที่มีความยาว 4 ไบต์เท่านั้น
- นำออบเจ็กต์
ClientInfo v4 ออกทั้งหมด แทนที่จะระบุการระบุตัวตนของไคลเอ็นต์โดยใช้ช่องเฉพาะ ให้ใช้ส่วนหัว User-Agent ที่รู้จักกันดี แม้ว่าจะไม่มีรูปแบบที่กำหนดไว้สำหรับการระบุไคลเอ็นต์ในส่วนหัวนี้ แต่เราขอแนะนำให้ระบุรหัสไคลเอ็นต์และเวอร์ชันไคลเอ็นต์เดิมโดยคั่นด้วยอักขระช่องว่างหรือเครื่องหมายทับ
- นำช่อง
client_states ออก ไม่จำเป็นอีกต่อไป
- ไม่จำเป็นต้องใส่
threat_types และฟิลด์ที่คล้ายกันอีกต่อไป
ควรทำการเปลี่ยนแปลงต่อไปนี้กับการตอบกลับ
- ระบบได้นำช่อง
minimum_wait_duration ออกแล้ว ไคลเอ็นต์สามารถส่งคำขอใหม่ได้ทุกเมื่อตามความจำเป็น
- เราได้ลดความซับซ้อนของออบเจ็กต์ v4
ThreatMatch ให้เป็นออบเจ็กต์ FullHash
- เราได้ลดความซับซ้อนของการแคชให้เหลือระยะเวลาแคชเดียว ดูขั้นตอนข้างต้นเพื่อโต้ตอบกับแคช
เนื้อหาของหน้าเว็บนี้ได้รับอนุญาตภายใต้ใบอนุญาตที่ต้องระบุที่มาของครีเอทีฟคอมมอนส์ 4.0 และตัวอย่างโค้ดได้รับอนุญาตภายใต้ใบอนุญาต Apache 2.0 เว้นแต่จะระบุไว้เป็นอย่างอื่น โปรดดูรายละเอียดที่นโยบายเว็บไซต์ Google Developers Java เป็นเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-08-10 UTC
[null,null,["อัปเดตล่าสุด 2025-08-10 UTC"],[],[],null,["# Migration From V4\n\nOne significant improvement of Google Safe Browsing v5 over v4 (specifically, [the v4 Update API](/safe-browsing/v4/update-api)) is data freshness and coverage. Since the protection highly depends on the client-maintained local database, the delay and size of the local database update is the main contributor of the missed protection. In v4, the typical client takes 20 to 50 minutes to obtain the most up-to-date version of threat lists. Unfortunately, phishing attacks spread fast: as of 2021, 60% of sites that deliver attacks live less than 10 minutes. Our analysis shows that around 25-30% of missing phishing protection is due to such data staleness. Further, some devices are not equipped to manage the entirety of the Google Safe Browsing threat lists, which continues to grow larger over time.\n\nIf you are currently using the [v4 Update API](/safe-browsing/v4/update-api), there is a seamless migration path from v4 to v5 without having to reset or erase the local database. This section documents how to do that.\n\n### Converting List Updates\n\nUnlike V4, where lists are identified by the tuple of threat type, platform type, threat entry type, in v5 lists are simply identified by name. This provides flexibility when multiple v5 lists could share the same threat type. Platform types and threat entry types are removed in v5.\n\nIn v4, one would use the [threatListUpdates.fetch method](/safe-browsing/reference/rest/v4/threatListUpdates/fetch) to download lists. In v5, one would switch to the [hashLists.batchGet method](/safe-browsing/reference/rest/v5/hashLists/batchGet).\n\nThe following changes should be made to the request:\n\n1. Remove the [v4 `ClientInfo` object](/safe-browsing/reference/rest/v4/ClientInfo) altogether. Instead of supplying a client's identification using a dedicated field, simply use the well-known [User-Agent header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). While there is no prescribed format for supplying the client identification in this header, we suggest simply including the original client ID and client version separated by a space character or a slash character.\n2. For each [v4 `ListUpdateRequest` object](/safe-browsing/reference/rest/v4/threatListUpdates/fetch#listupdaterequest):\n - Look up the corresponding v5 list name from the [available lists](/safe-browsing/reference/Local.Database#available-lists) and supply that name in the v5 request.\n - Remove unneeded fields such as `threat_entry_type` or `platform_type`.\n - The `state` field in v4 is directly compatible with the v5 `versions` field. The same byte string that would be sent to the server using the `state` field in v4 can simply be sent in v5 using the `versions` field.\n - For the v4 constraints, v5 uses a simplified version called [`SizeConstraints`](/safe-browsing/reference/rest/v5/SizeConstraints). Additional fields such as `region` should be dropped.\n\nThe following changes should be made to the response:\n\n1. The v4 [enum `ResponseType`](/safe-browsing/reference/rest/v4/threatListUpdates/fetch#ResponseType) is simply replaced by a boolean field named `partial_update`.\n2. The `minimum_wait_duration` field can now be zero or omitted. If it is, the client is requested to immediately make another request. This only happens when the client specifies in `SizeConstraints` a smaller constraint on max update size than the max database size.\n3. The Rice decoding algorithm for 32-bit integers will need to be adjusted. The difference is that the encoded data are encoded with a different endianness. In both v4 and v5, 32-bit hash prefixes are sorted lexicographically. But in v4, those prefixes are treated as little endian when sorted, whereas in v5 those prefixes are treated as big endian when sorted. This means that the client does not need to do any sorting, since lexicographic sorting is identical to numeric sorting with big endian. An example of this sort in the Chromium implementation of v4 can be found [here](https://source.chromium.org/chromium/chromium/src/+/main:components/safe_browsing/core/browser/db/v4_rice.cc;l=144-146;drc=8ba1bad80dc22235693a0dd41fe55c0fd2dbdabd). Such sorting can be removed.\n4. The Rice decoding algorithm will need to be implemented for other hash lengths as well.\n\n### Converting Hash Searches\n\nIn v4, one would use the [fullHashes.find method](/safe-browsing/reference/rest/v4/fullHashes/find) to get full hashes. The equivalent method in v5 is [the hashes.search method](/safe-browsing/reference/rest/v5/hashes/search).\n\nThe following changes should be made to the request:\n\n1. Structure the code to only send hash prefixes that are exactly 4 bytes in length.\n2. Remove the [v4 `ClientInfo` objects](/safe-browsing/reference/rest/v4/ClientInfo) altogether. Instead of supplying a client's identification using a dedicated field, simply use the well-known [User-Agent header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). While there is no prescribed format for supplying the client identification in this header, we suggest simply including the original client ID and client version separated by a space character or a slash character.\n3. Remove the `client_states` field. It is no longer necessary.\n4. It is no longer needed to include `threat_types` and similar fields.\n\nThe following changes should be made to the response:\n\n1. The `minimum_wait_duration` field has been removed. The client can always issue a new request on an as-needed basis.\n2. The [v4 `ThreatMatch` object](/safe-browsing/reference/rest/v4/ThreatMatch) has been simplified into the [`FullHash`](/safe-browsing/reference/rest/v5/hashes/search#FullHash) object.\n3. Caching has been simplified into a single cache duration. See the above procedures for interacting with the cache."]]
