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 字段用于指明在多长时间内网址必须被视为不安全网址 （请参阅缓存）。