Safe Browsing Lookup API (v4)

概览

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

检查网址

如需检查某个网址是否在“安全浏览”列表中，请向 threatMatch.find 方法发送 HTTP POST 请求：

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

示例：threatMatch.find

HTTP POST 请求

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

请求标头

请求标头包含请求网址和内容类型。请记得将 API 密钥中的网址替换为 API_KEY。

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

请求正文

请求正文包含客户端信息（ID 和版本）和威胁信息（列表名称和网址）。如需了解详情，请参阅 threatMatch.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

响应正文

响应正文包含匹配信息（列表名称和在这些列表中找到的网址）、元数据（如果有）以及缓存时长。如需了解详情，请参阅 threatMatch.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 对象会列出安全浏览列表的名称和网址（如果有）。在此示例中，我们在一个安全浏览列表 (MALWARE/WINDOWS/网址) 上找到了两个网址（urltocheck1.org 和 urltocheck2.org），因此返回了匹配信息。未在任一列表中找到第三个网址 (urltocheck3.org)，因此不会针对该网址返回任何信息。

元数据

threatEntryMetadata 字段是可选字段，它提供关于威胁匹配的更多信息。目前，MALWARE/WINDOWS/网址安全浏览列表提供了元数据（请参阅元数据）。

缓存时长

cacheDuration 字段指示必须将网址视为不安全的时间（请参阅缓存）。