Trang này được dịch bởi Cloud Translation API.

API tra cứu Duyệt web an toàn (phiên bản 4)

Tổng quan

Lookup API cho phép các ứng dụng khách của bạn gửi yêu cầu đến tính năng Duyệt web an toàn để kiểm tra xem URL có nằm trong bất kỳ danh sách Duyệt web an toàn nào không. Nếu tìm thấy URL trên một hoặc thêm danh sách thì thông tin khớp sẽ được trả về.

Kiểm tra URL

Để 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 tới threatMatches.find phương thức:

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á hoặc mã hoá.
Phản hồi HTTP POST trả về các URL phù hợp cùng với thời lượng của bộ nhớ đệm.

Ví dụ: shouldMatch.find

Yêu cầu POST qua HTTP

Trong ví dụ sau, hai danh sách Duyệt web an toàn và ba 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 đề yêu cầu

Tiêu đề yêu cầu bao gồm URL yêu cầu và loại nội dung. Nhớ thay thế khoá API cho 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ã nhận dạng 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 chi tiết, hãy xem threatMatch.find nội dung yêu cầu 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

Trường clientID và clientVersion phải xác định duy nhất một cách triển khai ứng dụng, chứ không phải một người dùng cá nhân. (Thông tin ứng dụng được dùng để 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ã ứng dụng khách, nhưng bạn nên chọn một tên thể hiện danh tính thực của khách hàng của bạn, chẳng hạn như tên công ty, được trình bày dưới dạng tất cả một từ, bằng chữ 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, có 2 danh sách được xác định: MALWARE/WINDOWS/URL và SOCIAL_EngineERING/WINDOWS/URL. Trước khi gửi yêu cầu, hãy đảm bảo loại các tổ hợp bạn chỉ định là hợp lệ (xem Danh sách duyệt web an toàn).

URL 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 vào hai danh sách Duyệt web an toàn.

Lưu ý: API Lookup và phương thức threatMatches phải luôn sử dụng trường URL. không bao giờ gặp trường hash (xem ThreatEntry).

Phản hồi POST qua HTTP

Trong ví dụ sau, phản hồi trả về một kết quả trùng khớp; hai trong số ba URL được chỉ định trong tìm thấy yêu cầu trên một trong hai danh sách 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 có 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 tìm thấy trên các danh sách đó, siêu dữ liệu (nếu có) và thời lượng của bộ nhớ đệm). Để biết thêm chi tiết, hãy xem threatMatch.find nội dung phản hồi 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ả trùng khớ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 chỉ 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 Duyệt web an toàn và URL (nếu có) có kết quả phù hợp. Trong ví dụ này, hai URL (urltocheck1.org và urltocheck2.org) được tìm thấy trên một trong danh sách Duyệt web An toàn (MALWARE/WINDOWS/URL) để thông tin trùng khớp được trả về. URL thứ ba Không tìm thấy (urltocheck3.org) trong một trong 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à trường không bắt buộc và cung cấp thêm thông tin về mối đe doạ. Hiện tại, siêu dữ liệu có sẵn cho danh sách Duyệt web an toàn của MALWARE/WINDOWS/URL (xem phần Siêu dữ liệu).

Thời lượng lưu trong bộ nhớ đệm

Trường cacheDuration cho biết khoảng thời gian URL phải được xem là không an toàn (xem phần Lưu vào bộ nhớ đệm).