Safe Browsing Lookup API (v4)

概览

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

检查网址

如需检查某个网址是否在安全浏览列表中,请向 threatMatches.find 方法发送 HTTP POST 请求:

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

示例:threatMatches.find

HTTP POST 请求

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

请求标头

请求标头包含请求网址和内容类型。请务必用您的 API 密钥替换网址中的 API_KEY

  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/"}
      ]
    }
  }
客户端信息

clientIDclientVersion 字段应唯一标识客户端实现,而不是单个用户。(客户端信息用于服务器端的日志记录和核算。您可以为客户端 ID 选择任何名称,但我们建议您选择一个能代表客户真实身份的名称,例如您的公司名称,该名称显示为一个单词,全部采用小写字母。)

安全浏览列表

我们将 threatTypeplatformTypethreatEntryType 字段组合起来标识(名称)安全浏览列表。在该示例中,标识了两个列表:MALWARE/WINDOWS/网址 和 SOCIAL_ENGINEERING/WINDOWS/网址。在发送请求之前,请确保您指定的类型组合有效(请参阅安全浏览列表)。

威胁网址

在此示例中,threatEntries 数组包含三个网址(urltocheck1.org、urltocheck2.org 和 urltocheck3.org),系统会根据两个安全浏览列表对这些网址进行检查。

注意:Lookup API 和 threatMatches 方法应始终使用 URL 字段,而非 hash 字段(请参阅 ThreatEntry)。

HTTP POST 响应

在下面的示例中,响应会返回一个匹配项;请求中指定的三个网址中有 2 个位于请求中指定的两个安全浏览列表中的一个。

响应标头

响应标头包含 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 对象会列出安全浏览列表的名称与网址(如果匹配)。在本示例中,我们在其中一个安全浏览列表 (MALWARE/WINDOWS/网址) 中发现了两个网址(urltocheck1.org 和 urltocheck2.org),因此系统返回了匹配信息。在这两个列表中都找不到第三个网址 (urltocheck3.org),因此系统不会返回此网址的任何信息。

元数据

threatEntryMetadata 字段为可选字段,用于提供有关威胁匹配的其他信息。目前,可在恶意软件/WINDOWS/网址安全浏览列表中找到元数据(请参阅元数据)。

缓存时长

cacheDuration 字段指示必须将网址视为不安全网址的时长(请参阅缓存)。