使用 Update API

概览

通过 Update API,您的客户端应用可以下载 Web Risk 列表的哈希版本,以存储在本地或内存数据库中。然后,您可以在本地检查网址。当在本地数据库中找到匹配项时,客户端会向 Web Risk 服务器发送请求,以验证该网址是否包含在 Web Risk 列表中。

更新本地数据库

要及时了解最新信息,客户端必须定期更新其本地数据库中的 Web Risk 列表。为了节省带宽,客户端应下载网址的哈希前缀,而不是原始网址。例如,如果“www.badurl.com/”位于 Web Risk 列表中,则客户端会下载该网址的 SHA256 哈希前缀,而不是网址本身。在大多数情况下,哈希前缀的长度为 4 个字节,这意味着在压缩之前下载单个列表条目的平均带宽费用为 4 个字节。

如要更新本地数据库中的 Web Risk 列表,请向 threatLists.computeDiff 方法发送 HTTP GET 请求:

  • HTTP GET 请求包含要更新列表的名称以及考虑内存和带宽限制的客户端约束。
  • HTTP GET 响应会返回完整更新或部分更新。响应还可以返回建议的等待时间,直到下一次计算差异操作。

示例:threatLists.computeDiff

HTTP GET 请求

在以下示例中,请求了 MALWARE Web Risk 列表的差异。如需了解详情,请参阅 threatLists.computeDiff 查询参数以及代码示例后面的说明。

HTTP 方法和网址:

GET "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"

如需发送请求,请选择以下方式之一:

curl

执行以下命令:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
""https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW""

PowerShell

执行以下命令:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri ""https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"" | Select-Object -Expand Content

您应会收到如下所示的 JSON 响应:

{
  "recommendedNextDiff": "2020-01-08T19:41:45.436722194Z",
  "responseType": "RESET",
  "additions": {
    "rawHashes": [
      {
        "prefixSize": 4,
        "rawHashes": "AArQMQAMoUgAPn8lAE..."
      }
    ]
  },
  "newVersionToken": "ChAIARAGGAEiAzAwMSiAEDABEPDyBhoCGAlTcIVL",
  "checksum": {
    "sha256": "wy6jh0+MAg/V/+VdErFhZIpOW+L8ulrVwhlV61XkROI="
  }
}

Web Risk 列表

threatType 字段用于标识 Web Risk 列表。在该示例中,请求了 MALWARE Web Risk 列表的差异。

版本令牌

versionToken 字段包含 Web Risk 列表的当前客户端状态。版本令牌在 threatLists.computeDiff 响应newVersionToken 字段中返回。 对于初始更新,请将 versionToken 字段留空。

尺寸限制

maxDiffEntries 字段指定客户端可以管理的更新总数(在此示例中为 2048)。maxDatabaseEntries 字段指定本地数据库可以管理的总条目数(在示例中为 4096)。只有当客户端具有内存或带宽限制时,才应设置尺寸限制。如需了解详情,请参阅更新限制)。

支持压缩

supportedCompressions 字段列出了客户端支持的压缩类型。在此示例中,客户端仅支持未压缩的原始数据。但 Web Risk 支持其他压缩类型。如需了解详情,请参阅压缩

HTTP GET 响应

在此示例中,响应使用请求的压缩类型返回 Web Risk 列表的部分更新。

响应正文

响应正文包含差异信息(响应类型、要应用于本地数据库的添加和移除项、新版本令牌以及校验和)。

在该示例中,响应还包含建议的下一个差异时间。如需了解详情,请参阅 threatLists.computeDiff 响应正文以及代码示例后面的说明。

{
  "responseType" :   "DIFF",
  "recommendedNextDiff": "2019-12-31T23:59:59.000000000Z",
  "additions": {
    "compressionType": "RAW",
    "rawHashes": [{
      "prefixSize": 4,
      "rawHashes":  "rnGLoQ=="
    }]
  },
  "removals": {
    "rawIndices": {
      "indices": [0, 2, 4]
    }
  },
  "newVersionToken": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
  "checksum": {
    "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
  },
  "recommendedNextDiff": "2019-07-17T15:01:23.045123456Z"
}

数据库差异

responseType 字段将指示部分更新 (DIFF) 或完全更新 (RESET)。在该示例中,返回了部分差异,因此响应包括添加和删除项。可能有多组添加项,但只有一组删除项。如需了解详情,请参阅 Database Diffs

新版本令牌

newVersionToken 字段包含新更新的 Web Risk 列表的新版本令牌。客户端必须为后续更新请求保存新的客户端状态(threatLists.computeDiff 请求中的 versionToken 字段)。

校验和

校验和可让客户端验证本地数据库是否未受到任何损坏。如果校验和不匹配,则客户端必须清除数据库并使用空 versionToken 字段重新发布更新。但是,在这种情况下,客户端仍必须遵循更新的时间间隔。如需了解详情,请参阅请求频率

recommendedNextDiff 字段指示在客户端发送其他更新请求之前应等待的时间戳。请注意,响应可能包含建议的等待时间段,也可能不包含。如需了解详情,请参阅请求频率

检查网址

如要检查某个网址是否在 Web Risk 列表中,客户端必须先计算该网址的哈希值和哈希前缀。如需了解详情,请参阅网址和哈希技术。然后,客户端会查询本地数据库以确定是否存在匹配。如果本地数据库中不存在哈希前缀,则该网址会被视为安全网址(即不在 Web Risk 列表中)。

如果本地数据库中存在哈希前缀(哈希前缀冲突),则客户端必须将哈希前缀发送到 Web Risk 服务器进行验证。服务器将返回包含给定哈希前缀的所有全长 SHA 256 哈希。如果其中一个全长哈希与相关网址的全长哈希值匹配,则该网址会被视为不安全网址。 如果没有任何全长的哈希与相关网址的全长哈希匹配,则该网址会被视为安全网址。

Google 绝不会了解您正在检查的网址。Google 确实会学习网址的哈希前缀,但哈希前缀不会提供有关实际网址的大量信息。

如要检查某个网址是否在 Web Risk 列表中,请向 hashes.search 方法发送 HTTP GET 请求:

  • HTTP GET 请求包含要检查的网址的哈希前缀。
  • HTTP GET 响应会返回匹配的全长哈希值以及正负到期时间。

示例:hashes.search

HTTP GET 请求

在以下示例中,将发送两个 Web Risk 列表的名称和哈希前缀进行比较和验证。如需了解详情,请参阅 hashes.search 查询参数以及代码示例后面的说明。

curl \
  -H "Content-Type: application/json" \
  "https://webrisk.googleapis.com/v1/hashes:search?key=YOUR_API_KEY&threatTypes=MALWARE&threatTypes=SOCIAL_ENGINEERING&hashPrefix=WwuJdQ%3D%3D"

Web Risk 列表

threatTypes 字段用于标识 Web Risk 列表。在此示例中,标识了两个列表:MALWARESOCIAL_ENGINEERING

威胁哈希前缀

hashPrefix 字段包含您要检查的网址的哈希前缀。此字段必须包含本地数据库中存在的确切哈希前缀。例如,如果本地哈希前缀的长度为 4 个字节,则 hashPrefix 字段的长度必须为 4 个字节。如果本地哈希前缀被延长为 7 个字节,则 hashPrefix 字段的长度必须为 7 个字节。

HTTP GET 响应

在以下示例中,响应将返回匹配的威胁(包含所匹配的 Web Risk 列表)以及到期时间。

响应正文

响应正文包含匹配信息(列表名称、全长哈希和缓存时长)。如需了解详情,请参阅 hashes.search 响应正文以及代码示例后面的说明。

{
  "threats": [{
      "threatTypes": ["MALWARE"],
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
      "expireTime": "2019-07-17T15:01:23.045123456Z"
    }, {
      "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
      "hash": "WwuJdQxaCSH453-uytERC456gf45rFExcE23F7-hnfD="
      "expireTime": "2019-07-17T15:01:23.045123456Z"
    },
  }],
  "negativeExpireTime": "2019-07-17T15:01:23.045123456Z"
}

匹配数

threats 字段会为哈希前缀返回匹配的全长哈希。 与这些哈希对应的网址被视为不安全。如果未找到与哈希前缀匹配的内容,则不会返回任何内容;则该哈希前缀对应的网址会被视为安全网址。

过期时间

expireTimenegativeExpireTime 字段指示直到哈希必须被视为不安全或安全为止的时间。如需了解详情,请参阅缓存