此页面由 Cloud Translation API 翻译。

Safe Browsing Lookup API (v4)

概览

借助 Lookup API，您的客户端应用可以向安全浏览功能发送请求服务器来检查网址是否包含在任何安全浏览列表中。如果网址存在于某一个或更多列表，则返回匹配信息。

检查网址

要检查某个网址是否在安全浏览列表中，请将 HTTP POST 请求发送到 threatMatches.find 方法：

HTTP POST 请求最多可包含 500 个网址。网址必须有效（请参阅 RFC 2396）但无需进行规范化或编码。
HTTP POST 响应会返回匹配的网址以及缓存时长。

示例：tallMatches.find

HTTP POST 请求

在以下示例中，系统会将两个安全浏览列表和三个网址发送给服务器，确定是否存在匹配。

请求标头

请求标头包含请求网址和内容类型。请务必将您在网址中为 API_KEY 设置的 API 密钥。

  POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1
  Content-Type: application/json

请求正文

请求正文包含客户端信息（ID 和版本）以及威胁信息（列表名称和网址）。有关详情，请参阅 threatMatches.find 请求正文以及相应代码示例的说明。

  {
    "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/"}
      ]
    }
  }

客户端信息

clientID 和 clientVersion 字段应唯一标识客户端实现，而不是单个用户（客户端信息用于服务器端日志记录和计算。您可以选择但我们建议您选择一个可代表客户端 ID 的真实身份的名称，客户（如您的公司名称）以全小写字母显示。

安全浏览列表

threatType、platformType 和 threatEntryType 字段组合在一起来识别（名称）安全浏览列表。此示例中标识了两个列表： MALWARE/WINDOWS/网址和 SOCIAL_ENGINEERING/WINDOWS/网址。在发送请求前，请确保请求类型指定的组合有效（请参阅安全浏览列表）。

威胁网址

在此示例中，threatEntries 数组包含三个网址（urltocheck1.org、urltocheck2.org、和 urltocheck3.org）将会被对照两个安全浏览列表进行检查。

注意：Lookup API 和 threatMatches 方法应始终使用 URL 字段，一律不使用 hash 字段（请参阅 ThreatEntry）。

HTTP POST 响应

在以下示例中，响应会返回一个匹配项；在会在请求中指定的两个安全浏览列表之一中找到此类请求。

响应标头

响应标头包含 HTTP 状态代码和内容类型

HTTP/1.1 200 OK
Content-Type: application/json

响应正文

响应正文包括匹配信息（列表名称和在以下位置找到的网址：这些列表、元数据（如果有）和缓存时长）。有关详情，请参阅 threatMatches.find 响应正文以及相应代码示例的说明。

注意：如果没有匹配项（即没有指定任何网址），（例如请求中指定的任何列表上）发现，则 HTTP POST 响应只会在响应正文中返回一个空对象。

{
  "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"
  }]
}

匹配

matches 对象会列出安全浏览列表的名称和网址（如果匹配。在该示例中，我们在某个网页上发现两个网址（urltocheck1.org 和 urltocheck2.org）安全浏览列表（恶意软件/窗口/网址），因此会返回匹配的信息。第三个网址 (urltocheck3.org) 在这两个列表中都找不到，因此系统不会返回此网址的任何信息。

元数据

threatEntryMetadata 字段为可选字段，提供威胁匹配。目前，元数据适用于恶意软件/WINDOWS/网址安全浏览列表（请参阅元数据）。

缓存时长

cacheDuration 字段用于指明在多长时间内网址必须被视为不安全网址（请参阅缓存）。