Tổng quan
API cập nhật cho phép các ứng dụng khách tải các phiên bản đã băm của danh sách Duyệt web an toàn xuống để lưu trữ trong cơ sở dữ liệu cục bộ. Sau đó, bạn có thể kiểm tra cục bộ URL. Chỉ khi tìm thấy kết quả trùng khớp trong cơ sở dữ liệu cục bộ, ứng dụng mới cần gửi yêu cầu đến các máy chủ của tính năng Duyệt web an toàn để xác minh xem URL có nằm trong danh sách của tính năng Duyệt web an toàn hay không.
Trước khi sử dụng API Cập nhật, bạn cần thiết lập cơ sở dữ liệu cục bộ. Tính năng Duyệt web an toàn cung cấp gói Go mà bạn có thể sử dụng để bắt đầu. Để biết thêm thông tin chi tiết, hãy xem phần Thiết lập cơ sở dữ liệu trong Cơ sở dữ liệu cục bộ.
Cập nhật cơ sở dữ liệu cục bộ
Để luôn nắm bắt thông tin mới nhất, máy khách phải cập nhật định kỳ các danh sách của tính năng Duyệt web an toàn trong cơ sở dữ liệu cục bộ của mình. Để tiết kiệm băng thông, ứng dụng sẽ tải tiền tố băm của URL xuống thay vì URL thô. Ví dụ: nếu "www.badurl.com/" nằm trong danh sách Duyệt web an toàn, ứng dụng sẽ tải tiền tố băm SHA256 của URL đó xuống thay vì chính URL đó. Trong hầu hết các trường hợp, tiền tố băm dài 4 byte, nghĩa là chi phí băng thông trung bình để tải một mục trong danh sách xuống là 4 byte trước khi nén.
Để cập nhật danh sách Duyệt web an toàn trong cơ sở dữ liệu cục bộ, hãy gửi yêu cầu HTTP POST đến phương thức threatListUpdates.fetch:
- Yêu cầu HTTP
POSTbao gồm tên của danh sách cần được cập nhật cùng với các quy tắc ràng buộc của ứng dụng khách để tính đến các giới hạn về bộ nhớ và băng thông. - Phản hồi HTTP
POSTtrả về thông tin cập nhật đầy đủ hoặc cập nhật một phần. Phản hồi có thể trả về thời gian chờ tối thiểu.
Ví dụ: mối đe doạListUpdate.fetch
Yêu cầu POST qua HTTP
Trong ví dụ sau, hệ thống yêu cầu cập nhật cho một danh sách của tính năng Duyệt web an toàn.
Tiêu đề của yêu cầu
Tiêu đề yêu cầu bao gồm URL yêu cầu và loại nội dung. Hãy nhớ thay thế khoá API cho API_KEY trong URL.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
Nội dung yêu cầu
Phần nội dung yêu cầu bao gồm thông tin ứng dụng (mã nhận dạng và phiên bản) và thông tin cập nhật (tên danh sách, trạng thái danh sách và các quy tắc ràng buộc của ứng dụng). Để biết thêm thông tin chi tiết, hãy xem nội dung yêu cầu threatListUpdate.fetch và nội dung giải thích tuân theo ví dụ về mã.
{
"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"]
}
}]
}
Thông tin khách hàng
Các trường clientID và clientVersion phải xác định riêng một cách triển khai ứng dụng chứ không phải của từng người dùng. (Thông tin ứng dụng được dùng trong tính năng ghi nhật ký phía máy chủ. Bạn có thể chọn bất kỳ tên nào cho mã khách hàng, nhưng bạn nên chọn tên thể hiện danh tính thực sự của khách hàng, chẳng hạn như tên công ty của bạn, được trình bày dưới dạng tất cả một từ và viết thường.)
Danh sách của tính năng Duyệt web an toàn
Các trường threatType, platformType và threatEntryType
được kết hợp để xác định (đặt tên) cho các danh sách của tính năng Duyệt web an toàn. Trong ví dụ này, một danh sách được xác định:
MALWARE/WINDOWS/URL. Trước khi gửi yêu cầu, hãy đảm bảo các tổ hợp loại mà bạn chỉ định là hợp lệ (xem Danh sách duyệt web an toàn).
Trạng thái ứng dụng
Trường state lưu giữ trạng thái ứng dụng hiện tại của danh sách Duyệt web an toàn.
(Trạng thái ứng dụng được trả về trong trường newClientState của phản hồi threatListUpdate.fetch.)
Đối với các bản cập nhật ban đầu, hãy để trống trường state.
Giới hạn về kích thước
Trường maxUpdateEntries chỉ định tổng số nội dung cập nhật mà ứng dụng có thể quản lý (trong ví dụ: 2048). Trường maxDatabaseEntries chỉ định tổng số mục mà cơ sở dữ liệu cục bộ có thể quản lý (trong ví dụ: 4096). Khách hàng nên đặt các giới hạn về kích thước để bảo vệ các giới hạn về bộ nhớ và băng thông, cũng như để chống lại sự tăng trưởng của danh sách. Để biết thêm thông tin,
(xem bài viết Cập nhật quy tắc ràng buộc).
Các loại nén được hỗ trợ
Trường supportedCompressions liệt kê các loại nén mà ứng dụng hỗ trợ. Trong ví dụ này, ứng dụng chỉ hỗ trợ dữ liệu thô, chưa nén. Tuy nhiên, Duyệt web an toàn hỗ trợ các loại nén bổ sung (xem nội dung Nén).
phản hồi POST qua HTTP
Trong ví dụ này, phản hồi trả về nội dung cập nhật một phần cho danh sách Duyệt web an toàn bằng loại nén được yêu cầu.
Tiêu đề phản hồi
Tiêu đề phản hồi bao gồm mã trạng thái HTTP và loại nội dung. Những ứng dụng nhận được mã trạng thái không phải HTTP/200 sẽ phải chuyển sang chế độ thời gian đợi (xem phần Tần suất yêu cầu).
HTTP/1.1 200 OK Content-Type: application/json
Nội dung phản hồi
Nội dung phản hồi bao gồm thông tin cập nhật (tên danh sách, loại phản hồi, các thao tác thêm và xoá sẽ áp dụng cho cơ sở dữ liệu cục bộ, trạng thái ứng dụng mới và tổng kiểm). Trong ví dụ này, phản hồi cũng bao gồm thời gian chờ tối thiểu. Để biết thêm thông tin chi tiết, hãy xem nội dung phản hồi threatListUpdate.fetch và nội dung giải thích tuân theo ví dụ về mã.
{
"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"
}
Cập nhật cơ sở dữ liệu
Trường responseType sẽ cho biết nội dung cập nhật một phần hoặc toàn bộ. Trong ví dụ này, hệ thống trả về một phần cập nhật, vì vậy, phản hồi sẽ bao gồm cả nội dung bổ sung và xoá. Có thể có nhiều tập hợp bổ sung, nhưng chỉ có một tập hợp xoá (xem nội dung Cập nhật cơ sở dữ liệu).
Trạng thái ứng dụng mới
Trường newClientState lưu giữ trạng thái ứng dụng mới cho danh sách Duyệt web an toàn mới được cập nhật.
Ứng dụng phải lưu trạng thái ứng dụng mới cho các yêu cầu cập nhật tiếp theo (trường state trong yêu cầu threatListUpdate.fetch hoặc trường clientStates trong yêu cầu fullHashes.find).
Giá trị tổng kiểm
Giá trị tổng kiểm này cho phép ứng dụng xác minh rằng cơ sở dữ liệu cục bộ không bị hỏng. Nếu giá trị tổng kiểm không khớp, máy khách phải xoá cơ sở dữ liệu và phát hành lại bản cập nhật có trường state trống. Tuy nhiên, các ứng dụng trong trường hợp này vẫn phải tuân theo các khoảng thời gian cập nhật (xem bài viết Tần suất yêu cầu).
Thời gian chờ tối thiểu
Trường minimumWaitDuration cho biết ứng dụng phải đợi 593,44 giây (9,89 phút) thì mới có thể gửi yêu cầu cập nhật khác. Xin lưu ý rằng phản hồi có thể có hoặc không có thời gian chờ (xem phần Tần suất yêu cầu).
Đang kiểm tra URL
Để kiểm tra xem một URL có nằm trong danh sách của tính năng Duyệt web an toàn hay không, trước tiên, khách hàng phải tính toán tiền tố băm và hàm băm của URL (xem phần URL và băm). Sau đó, máy khách sẽ truy vấn cơ sở dữ liệu cục bộ để xác định xem có kết quả trùng khớp hay không. Nếu tiền tố băm không có trong cơ sở dữ liệu cục bộ, thì URL đó được coi là an toàn (không có trong danh sách của tính năng Duyệt web an toàn).
Nếu tiền tố băm có trong cơ sở dữ liệu cục bộ (xung đột tiền tố băm), thì máy khách phải gửi tiền tố hàm băm đó đến máy chủ của tính năng Duyệt web an toàn để xác minh. Máy chủ sẽ trả về tất cả hàm băm SHA 256 đủ độ dài có chứa tiền tố hàm băm nhất định. Nếu một trong các hàm băm đủ thời lượng đó khớp với hàm băm đủ thời lượng của URL có liên quan, thì URL đó sẽ bị coi là không an toàn. Nếu không có hàm băm đủ độ dài nào khớp với hàm băm đủ độ dài của URL được đề cập, thì URL đó được coi là an toàn.
Google không bao giờ tìm hiểu về URL mà bạn đang kiểm tra. Google có tìm hiểu tiền tố băm của các URL, nhưng tiền tố băm không cung cấp nhiều thông tin về URL thực tế.
Để kiểm tra xem một URL có nằm trong danh sách Duyệt web an toàn hay không, hãy gửi yêu cầu HTTP POST đến phương thức fullHashes.find:
- Yêu cầu HTTP
POSTcó thể bao gồm tối đa 500 mục đe doạ. - Yêu cầu HTTP
POSTbao gồm các tiền tố băm của các URL cần kiểm tra. Khách hàng nên nhập nhiều mục nhập các mối đe doạ vào một yêu cầu duy nhất để giảm mức sử dụng băng thông. - Phản hồi
POSTHTTP sẽ trả về các hàm băm đủ thời lượng phù hợp cùng với thời lượng bộ nhớ đệm dương và âm. Phản hồi có thể trả về thời gian chờ tối thiểu.
Ví dụ: fullHashes.find
Yêu cầu POST qua HTTP
Trong ví dụ sau, tên của 2 danh sách Duyệt web an toàn và 3 tiền tố băm được gửi để so sánh và xác minh.
Tiêu đề của yêu cầu
Tiêu đề yêu cầu bao gồm URL yêu cầu và loại nội dung. Hãy nhớ thay thế khoá API cho API_KEY trong URL.
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Nội dung yêu cầu
Nội dung yêu cầu bao gồm thông tin ứng dụng (mã nhận dạng và phiên bản), trạng thái ứng dụng và thông tin về mối đe doạ (tên danh sách và tiền tố băm). Đối với yêu cầu JSON, bạn phải gửi tiền tố băm ở dạng được mã hoá base64. Để biết thêm thông tin chi tiết, hãy xem nội dung yêu cầu fullHashes.find và nội dung giải thích tuân theo ví dụ về mã.
{
"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=="}
]
}
}
Thông tin khách hàng
Các trường clientID và clientVersion phải xác định riêng một cách triển khai ứng dụng chứ không phải của từng người dùng. (Thông tin ứng dụng được dùng trong tính năng ghi nhật ký phía máy chủ. Bạn có thể chọn bất kỳ tên nào cho
mã khách hàng, nhưng bạn nên chọn tên thể hiện danh tính thực sự của khách hàng, chẳng hạn như
tên công ty của bạn, được trình bày dưới dạng tất cả một từ và viết thường.)
Tất cả trạng thái của ứng dụng
Trường clientStates lưu giữ các trạng thái ứng dụng cho tất cả danh sách Duyệt web an toàn trong cơ sở dữ liệu cục bộ của ứng dụng. (Trạng thái ứng dụng được trả về trong trường newClientState của phản hồi threatListUpdate.fetch.)
Danh sách của tính năng Duyệt web an toàn
Các trường threatTypes, platformTypes và threatEntryTypes kết hợp để xác định (đặt tên) cho các danh sách Duyệt web an toàn. Trong ví dụ này, hai danh sách được xác định: MALWARE/WINDOWS/URL và SOCIAL_SPECIFICERING/WINDOWS/URL. Trước khi gửi yêu cầu, hãy đảm bảo các tổ hợp loại mà bạn chỉ định là hợp lệ (xem Danh sách duyệt web an toàn).
Tiền tố băm về mối đe doạ
Mảng mối đe doạ chứa các tiền tố băm của những URL mà bạn muốn kiểm tra.
Trường hash phải chứa chính xác tiền tố băm có trong cơ sở dữ liệu cục bộ. Ví dụ: nếu tiền tố băm cục bộ dài 4 byte thì mục nhập mối đe doạ phải dài 4 byte. Nếu tiền tố băm cục bộ được kéo dài đến 7 byte thì mục nhập mối đe doạ phải dài 7 byte.
Trong ví dụ này, yêu cầu bao gồm ba tiền tố băm. Cả ba tiền tố sẽ được so sánh với từng danh sách của tính năng Duyệt web an toàn để xác định xem có hàm băm đủ thời lượng phù hợp hay không.
Lưu ý: Update API và phương thức fullHashes.find phải luôn sử dụng trường hash, tuyệt đối không sử dụng trường URL (xem phần ThreatEntry).
phản hồi POST qua HTTP
Trong ví dụ sau, phản hồi trả về dữ liệu trùng khớp, được sắp xếp theo danh sách Duyệt web an toàn, cùng với bộ nhớ đệm và thời lượng chờ.
Tiêu đề phản hồi
Tiêu đề phản hồi bao gồm mã trạng thái HTTP và loại nội dung. Các ứng dụng nhận được mã trạng thái không phải HTTP/200 phải đợi (xem Tần suất yêu cầu).
HTTP/1.1 200 OK Content-Type: application/json
Nội dung phản hồi
Nội dung phản hồi bao gồm thông tin trùng khớp (tên danh sách và hàm băm đầy đủ độ dài, siêu dữ liệu, nếu có và thời lượng bộ nhớ đệm). Trong ví dụ này, nội dung phản hồi cũng bao gồm khoảng thời gian chờ tối thiểu. Để biết thêm thông tin chi tiết, hãy xem nội dung phản hồi fullHashes.find và nội dung giải thích tuân theo ví dụ về mã.
{
"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"
}
Khớp với
Đối tượng Đối sánh sẽ trả về một hàm băm đủ độ dài phù hợp cho hai trong số các tiền tố băm. Các URL tương ứng với các hàm băm này bị coi là không an toàn. Không tìm thấy kết quả khớp cho tiền tố hàm băm thứ ba, vì vậy, không có kết quả trả về nào; URL tương ứng với tiền tố hàm băm này được coi là an toàn.
Xin lưu ý rằng ví dụ này khớp một hàm băm đủ thời lượng với một tiền tố hàm băm; tuy nhiên, có thể có nhiều hàm băm đầy đủ liên kết với cùng một tiền tố hàm băm.
Metadata
Trường threatEntryMetadata là không bắt buộc và cung cấp thêm thông tin về việc so khớp mối đe doạ. Hiện tại, bạn có thể sử dụng siêu dữ liệu cho danh sách Duyệt web an toàn MALWARE/WINDOWS/URL (xem Siêu dữ liệu).
Thời lượng của bộ nhớ đệm
Các trường cacheDuration và negativeCacheDuration cho biết khoảng thời gian các hàm băm phải được coi là không an toàn hoặc an toàn (xem phần Lưu vào bộ nhớ đệm).
Thời gian chờ tối thiểu
Trường minimumWaitDuration cho biết ứng dụng phải đợi 300 giây (5 phút) trước khi gửi một yêu cầu fullHashes khác. Xin lưu ý rằng thời gian chờ có thể được đưa hoặc không được đưa vào phản hồi (xem phần Tần suất yêu cầu).