Migration From V4
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Một điểm cải tiến đáng kể của Google Safe Browsing phiên bản 5 so với phiên bản 4 (cụ thể là Update API phiên bản 4) là tính mới và phạm vi của dữ liệu. Vì tính năng bảo vệ phụ thuộc nhiều vào cơ sở dữ liệu cục bộ do máy khách duy trì, nên độ trễ và kích thước của bản cập nhật cơ sở dữ liệu cục bộ là yếu tố chính khiến tính năng bảo vệ bị bỏ lỡ. Trong phiên bản 4, ứng dụng khách thông thường mất từ 20 đến 50 phút để nhận được phiên bản danh sách mối đe doạ mới nhất. Thật không may, các cuộc tấn công giả mạo lan rộng rất nhanh: tính đến năm 2021, 60% trang web thực hiện các cuộc tấn công chỉ hoạt động dưới 10 phút. Kết quả phân tích của chúng tôi cho thấy khoảng 25-30% trường hợp thiếu tính năng bảo vệ khỏi hành vi lừa đảo là do dữ liệu không còn mới. Ngoài ra, một số thiết bị không được trang bị để quản lý toàn bộ danh sách các mối đe doạ của tính năng Duyệt web an toàn của Google. Danh sách này sẽ tiếp tục tăng lên theo thời gian.
Nếu hiện đang sử dụng Update API phiên bản 4, bạn có thể di chuyển liền mạch từ phiên bản 4 sang phiên bản 5 mà không cần phải đặt lại hoặc xoá cơ sở dữ liệu cục bộ. Phần này trình bày cách thực hiện việc đó.
Chuyển đổi nội dung cập nhật danh sách
Không giống như phiên bản 4 (trong đó danh sách được xác định bằng bộ gồm loại mối đe doạ, loại nền tảng, loại mục nhập mối đe doạ), trong phiên bản 5, danh sách chỉ được xác định bằng tên. Điều này mang lại sự linh hoạt khi nhiều danh sách v5 có thể dùng chung cùng một loại mối đe doạ. Các loại nền tảng và loại mục nhập mối đe doạ sẽ bị xoá trong phiên bản 5.
Trong phiên bản 4, bạn có thể dùng phương thức threatListUpdates.fetch để tải danh sách xuống. Trong phiên bản 5, bạn sẽ chuyển sang phương thức hashLists.batchGet.
Bạn cần thực hiện những thay đổi sau đối với yêu cầu:
- Xoá hoàn toàn đối tượng
ClientInfo v4. Thay vì cung cấp thông tin nhận dạng của một ứng dụng bằng một trường chuyên dụng, bạn chỉ cần sử dụng tiêu đề User-Agent quen thuộc. Mặc dù không có định dạng bắt buộc để cung cấp thông tin nhận dạng ứng dụng khách trong tiêu đề này, nhưng bạn chỉ cần thêm mã ứng dụng khách ban đầu và phiên bản ứng dụng khách, được phân tách bằng một ký tự khoảng trắng hoặc ký tự dấu gạch chéo.
- Đối với mỗi đối tượng
ListUpdateRequest v4:
- Tra cứu tên danh sách v5 tương ứng trong các danh sách có sẵn và cung cấp tên đó trong yêu cầu v5.
- Xoá các trường không cần thiết, chẳng hạn như
threat_entry_type hoặc platform_type.
- Trường
state trong phiên bản 4 tương thích trực tiếp với trường versions trong phiên bản 5. Bạn chỉ cần gửi cùng một chuỗi byte sẽ được gửi đến máy chủ bằng cách sử dụng trường state trong phiên bản 4 bằng cách sử dụng trường versions trong phiên bản 5.
- Đối với các ràng buộc v4, v5 sử dụng một phiên bản đơn giản hoá có tên là
SizeConstraints. Bạn nên bỏ các trường bổ sung như region.
Bạn nên thực hiện những thay đổi sau đối với phản hồi:
- enum
ResponseType v4 chỉ được thay thế bằng một trường boolean có tên là partial_update.
- Giờ đây, bạn có thể đặt trường
minimum_wait_duration thành 0 hoặc bỏ qua trường này. Nếu có, máy khách sẽ được yêu cầu đưa ra một yêu cầu khác ngay lập tức. Điều này chỉ xảy ra khi ứng dụng chỉ định trong SizeConstraints một ràng buộc nhỏ hơn về kích thước tối đa của bản cập nhật so với kích thước tối đa của cơ sở dữ liệu.
- Bạn cần điều chỉnh thuật toán giải mã Rice cho số nguyên 32 bit. Điểm khác biệt là dữ liệu được mã hoá sẽ được mã hoá bằng một thứ tự byte khác. Trong cả phiên bản 4 và phiên bản 5, tiền tố hàm băm 32 bit được sắp xếp theo thứ tự từ điển. Nhưng trong phiên bản 4, các tiền tố đó được coi là little endian khi được sắp xếp, trong khi trong phiên bản 5, các tiền tố đó được coi là big endian khi được sắp xếp. Điều này có nghĩa là ứng dụng không cần thực hiện bất kỳ thao tác sắp xếp nào, vì thao tác sắp xếp theo từ điển giống với thao tác sắp xếp theo số với thứ tự byte lớn. Bạn có thể xem ví dụ về loại này trong quá trình triển khai v4 của Chromium tại đây. Bạn có thể xoá cách sắp xếp như vậy.
- Bạn cũng cần triển khai thuật toán giải mã Rice cho các độ dài băm khác.
Chuyển đổi các cụm từ tìm kiếm có hàm băm
Trong phiên bản 4, người dùng sẽ sử dụng phương thức fullHashes.find để nhận các giá trị băm đầy đủ. Phương thức tương đương trong phiên bản 5 là phương thức hashes.search.
Bạn cần thực hiện những thay đổi sau đối với yêu cầu:
- Cấu trúc mã để chỉ gửi tiền tố băm có độ dài chính xác là 4 byte.
- Xoá hoàn toàn các đối tượng
ClientInfo v4. Thay vì cung cấp thông tin nhận dạng của một ứng dụng bằng một trường chuyên dụng, bạn chỉ cần sử dụng tiêu đề User-Agent quen thuộc. Mặc dù không có định dạng bắt buộc để cung cấp thông tin nhận dạng ứng dụng khách trong tiêu đề này, nhưng bạn chỉ cần thêm mã ứng dụng khách ban đầu và phiên bản ứng dụng khách, được phân tách bằng một ký tự khoảng trắng hoặc ký tự dấu gạch chéo.
- Xoá trường
client_states. Dữ liệu này không còn cần thiết nữa.
- Bạn không cần phải thêm
threat_types và các trường tương tự nữa.
Bạn nên thực hiện những thay đổi sau đối với phản hồi:
- Đã xoá trường
minimum_wait_duration. Máy khách luôn có thể đưa ra yêu cầu mới khi cần.
- Đối tượng v4
ThreatMatch đã được đơn giản hoá thành đối tượng FullHash.
- Quy trình lưu vào bộ nhớ đệm đã được đơn giản hoá thành một khoảng thời gian lưu vào bộ nhớ đệm duy nhất. Hãy xem các quy trình ở trên để tương tác với bộ nhớ đệm.
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-08-10 UTC.
[null,null,["Cập nhật lần gần đây nhất: 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."]]
