Tổng quan
API Tra cứu cho phép các ứng dụng khách của bạn gửi yêu cầu đến máy chủ của tính năng Duyệt web an toàn để kiểm tra xem các URL có nằm trong danh sách nào của danh sách Duyệt web an toàn hay không. Nếu URL được tìm thấy trong một hoặc nhiều danh sách, thì thông tin trùng khớp sẽ được trả về.
Đang kiểm tra URL
Để kiểm tra xem một URL có 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 threatMatches.find:
- Yêu cầu HTTP
POST
có thể bao gồm tối đa 500 URL. Các URL phải hợp lệ (xem RFC 2396) nhưng không cần phải chuẩn hoá hay mã hoá. - Phản hồi HTTP
POST
trả về các URL phù hợp cùng với thời lượng bộ nhớ đệm.
Ví dụ: mối đe doạ.find
Yêu cầu POST qua HTTP
Trong ví dụ sau, 2 danh sách của tính năng Duyệt web an toàn và 3 URL được gửi đến máy chủ để xác định xem có kết quả trùng khớp hay không.
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 bằng API_KEY
trong URL.
POST https://safebrowsing.googleapis.com/v4/threatMatches: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ã và phiên bản) và thông tin về mối đe doạ (tên danh sách và URL). Để biết thêm thông tin chi tiết, hãy xem nội dung yêu cầu threat phù.find và nội dung giải thích tuân theo ví dụ về mã.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "threatInfo": { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "platformTypes": ["WINDOWS"], "threatEntryTypes": ["URL"], "threatEntries": [ {"url": "http://www.urltocheck1.org/"}, {"url": "http://www.urltocheck2.org/"}, {"url": "http://www.urltocheck3.com/"} ] } }
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 cho mục đích ghi nhật ký và kế toán 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, viết 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ên) 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 kiểu mà bạn chỉ định là hợp lệ (xem Danh sách duyệt web an toàn).
URL của mối đe doạ
Trong ví dụ này, mảng threatEntries
chứa 3 URL (urltocheck1.org, urltocheck2.org,
và urltocheck3.org) sẽ được kiểm tra dựa trên 2 danh sách của tính năng Duyệt web An toàn.
Lưu ý: Lookup API và phương thức threatMatches
phải luôn sử dụng trường URL
, tuyệt đối không sử dụng trường hash
(xem nội dung ThreatEntry).
phản hồi POST qua HTTP
Trong ví dụ sau, phản hồi trả về kết quả trùng khớp; 2 trong số 3 URL được chỉ định trong yêu cầu sẽ nằm ở 1 trong 2 danh sách của tính năng Duyệt web an toàn được chỉ định trong 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.
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à URL có trong các danh sách đó, siêu dữ liệu, nếu có và thời lượng bộ nhớ đệm). Để biết thêm thông tin chi tiết, hãy xem nội dung phản hồi threat phù.find và nội dung giải thích tuân theo ví dụ về mã.
Lưu ý: Nếu không có kết quả nào phù hợp (nghĩa là nếu không có URL nào được chỉ định trong yêu cầu được tìm thấy trên bất kỳ danh sách nào được chỉ định trong yêu cầu), thì phản hồi HTTP POST
sẽ chỉ đơn giản là trả về một đối tượng trống trong nội dung phản hồi.
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": {"url": "http://www.urltocheck1.org/"}, "threatEntryMetadata": { "entries": [{ "key": "malware_threat_type", "value": "landing" }] }, "cacheDuration": "300.000s" }, { "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": {"url": "http://www.urltocheck2.org/"}, "threatEntryMetadata": { "entries": [{ "key": "malware_threat_type", "value": "landing" }] }, "cacheDuration": "300.000s" }] }
Khớp với
Đối tượng matches
liệt kê tên của các danh sách của tính năng Duyệt web an toàn và các URL (nếu có). Trong ví dụ này, hai URL (urltocheck1.org và urltocheck2.org) được tìm thấy trên một trong những
danh sách Duyệt web an toàn (MALWARE/WINDOWS/URL) và thông tin trùng khớp sẽ được trả về. Không tìm thấy URL thứ ba (urltocheck3.org) trong cả hai danh sách, vì vậy không có thông tin nào được trả về cho URL này.
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
Trường cacheDuration
cho biết khoảng thời gian URL bị coi là không an toàn (xem nội dung Lưu vào bộ nhớ đệm).