缓存

本文档适用于以下方法：

• Lookup API (v4)： threatMatches.find
• Update API (v4)： fullHashes.find

关于缓存

为了减少客户端带宽用量并保护 Google 免受流量高峰， 需要 Lookup API 和 Update API 来创建和维护威胁数据的本地缓存。 对于 Lookup API，使用缓存来减少 threatMatches 的数量 向 Google 发送的请求对于 Update API，缓存用于减少客户端向 Google 发送的 fullHashes 请求的数量。每个 API 的缓存协议为 如下所述。

Lookup API

Lookup API 的客户端应在指定时长内缓存返回的每个 ThreatMatch 项 由其 cacheDuration 字段决定。然后，客户端需要先查询缓存，然后才能执行后续操作， 向服务器发出 threatMatches 请求。如果之前返回的 ThreatMatch 的缓存时长 尚未过期，则客户端应假定该项仍不安全。正在缓存 ThreatMatch 项 可能会减少客户端发出的 API 请求数量。

示例： ThreatMatches.find

点击表标头中的请求和响应链接可查看完整示例。

"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]

Update API

为减少使用 Update API 向 Google 发送的 fullHashes 请求总数，客户端 都需要用到它来维护本地缓存该 API 建立了两种类型的缓存，即正缓存和负缓存。

正缓存

为防止客户端反复询问特定不安全的全哈希的状态， 每个返回的 ThreatMatch 都包含一个正缓存时长（由 cacheDuration 字段定义）， 它表示整个哈希被视为不安全的时长。

负缓存

为防止客户端反复询问特定安全完整哈希的状态， 每个 fullHashes 响应为请求的前缀（由 negativeCacheDuration 字段）。此时长表示请求的所有完整哈希值的时长 前缀被视为对于请求的列表是安全的，服务器以 不安全。这种缓存特别重要，因为它可以防止可能产生的流量过载， 哈希前缀冲突。

咨询缓存

当客户端要检查网址的状态时，首先会计算其完整哈希值。如果整个 哈希的前缀存在于本地数据库中，则客户端应在请求响应之前查询其缓存， 向服务器发出 fullHashes 请求。

首先，客户应检查缓存命中是否为正。如果存在未过期的正缓存 则视为不安全。如果正缓存条目 已过期，客户端必须发送 fullHashes 请求来获取关联的本地前缀。根据 如果服务器返回完整的哈希值，就会被视为不安全；否则，它会被视为 安全。

如果完整哈希值没有正缓存条目，则客户端应检查负缓存条目 缓存命中。如果关联的本地前缀存在未过期的排除缓存条目， 被认为是安全的。如果排除缓存条目已过期或不存在，客户端 必须针对关联的本地前缀发送 fullHashes 请求，并照常解读响应。

更新缓存

每当收到 fullHashes 响应时，都应更新客户端缓存。正缓存 应根据 cacheDuration 字段为完整哈希创建或更新条目。哈希前缀的 此外，还应根据响应的 negativeCacheDuration 创建或更新负缓存时长。 字段。

如果后续的 fullHashes 请求未返回当前正数的完整哈希值 已缓存，则客户端无需删除正缓存条目。您无需为此担心 因为正向缓存持续时间通常很短（几分钟），所以在实践中 假正例的校正。

示例场景

在以下示例中，假设 h(url) 是网址的哈希前缀， H(url) 是 网址的完整长度哈希值。即 h(url) = SHA256(url).substr(4), H(url) = SHA256(url)。

现在，假设一个客户端（具有空缓存）访问 example.com/，并看到 h(example.com/) 为 保存在本地数据库中。客户端请求哈希前缀 h(example.com/) 的完整长度哈希 之后接收回完整长度的哈希值 H(example.com/) 以及正缓存时长 5 分钟，负缓存时长为 1 小时。

5 分钟正缓存时长告诉客户端完整长度哈希多长时间 必须在不发送另一个 fullHashes 请求的情况下将 H(example.com/) 视为不安全。5 点之后 分钟，如果将fullHashes 客户再次访问 example.com/。客户端应重置哈希前缀的负缓存时长 每个新响应。

1 小时的负缓存持续时间告诉客户端所有其他完整长度的哈希多长时间 对于 1 小时的时长内，每个符合以下条件的网址都必须视为安全网址：h(网址) = h(example.com/)；并且 因此不会导致 fullHashes 请求（假设 H(网址) != H(example.com/)）。

如果 fullHashes 响应包含零个匹配项，并且设置了负缓存时长，则 客户端不得针对所请求的给定前缀发出任何 fullHashes 请求， 缓存时长为负。

如果 fullHashes 响应包含一个或多个匹配项，则仍会设置负缓存时长 。在这种情况下，单个完整哈希的缓存时长表示 这个特定完整长度的哈希必须被客户端视为不安全。在 ThreatMatch 缓存之后 持续时间过后，客户端必须通过发出 fullHashes 请求来刷新完整长度哈希， 该哈希前缀。在该部分中， 负缓存时长不适用。响应的负缓存时长仅适用于 fullHashes 响应中不存在的完整长度哈希。对于 出现，则客户端必须避免发出任何 fullHashes 请求 直到排除缓存时长过去为止。

示例：fullHashes.find

点击表标头中的请求和响应链接可查看完整示例。

"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"

"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"

"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"