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

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).