缓存

本文档适用于以下方法：

Lookup API：uris.search
Update API：hashes.search

关于缓存

为了减少客户端带宽用量并防止 Google 出现流量高峰，Lookup API 和 Update API 的客户端都必须创建并维护威胁数据的本地缓存。Lookup API 使用缓存来减少客户端向 Google 发送的 uris.search 请求的数量。对于 Update API，缓存用于减少客户端向 Google 发送的 hashes.search 请求的数量。以下列出了每个 API 的缓存协议。

Lookup API

Lookup API 的客户端应缓存每个返回的 ThreatUrl 项，直到 expireTime 字段中定义的时间为止。然后，客户端需要在向服务器发出后续 uris.search 请求之前查询缓存。如果之前返回的 ThreatUrl 的缓存条目尚未过期，则客户端应假定该条目仍然不安全。缓存 ThreatUrl 项可能会减少客户端发出的 API 请求数量。

Update API

如要减少使用 Update API 向 Google 发送的 hashes.search 请求总数，客户端需要维护本地缓存。该 API 建立两种缓存类型：正缓存和负缓存。

正缓存

为了防止客户端重复询问特定不安全完整哈希的状态，每个返回的 ThreatHash 都包含正缓存时间（由 expireTime 字段定义）。在此时间之前，完整哈希会被视为不安全。

负缓存

为了防止客户端重复询问特定的安全完整哈希的状态，响应为请求的前缀（由 negativeExpireTime 字段定义）定义了负缓存持续时间。在此时间之前，对于请求的威胁类型，所有带有请求前缀的完整哈希都被认为是安全的，除非服务器返回的是不安全的。这种缓存特别重要，因为它可以防止流量哈希过载，该过载可能是因为流量前缀与接收大量流量的安全网址发生冲突。

咨询缓存

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

首先，客户应检查缓存命中是否为正。如果感兴趣的完整哈希存在未过期的正缓存条目，则应将其视为不安全的。如果正缓存条目过期，则客户端必须为关联的本地前缀发送 hashes.search 请求。根据协议，如果服务器返回完整哈希，则被视为不安全；否则会被视为安全

如果没有对完整哈希的正缓存条目，则客户端应检查缓存命中是否为负。如果关联的本地前缀存在未过期的负缓存条目，则认为完整哈希是安全的。如果负缓存条目已过期或不存在，则客户端必须为关联的本地前缀发送 hashes.search 请求，并将响应解释为正常。

更新缓存

每当收到 hashes.search 响应时，都应更新客户端缓存。应为每个 expireTime 字段的完整哈希创建或更新正缓存条目。应为每个 negativeExpireTime 字段创建或更新哈希前缀的负缓存持续时长。

如果后续 hashes.search 请求未返回当前正缓存的完整哈希，则客户端不需要移除正缓存条目。这在实际操作中无需担心，因为正缓存持续时间通常很短（几分钟），可快速纠正假正例。

示例场景

在以下示例中，假设 h （网址）是网址的哈希前缀，而 H（网址）是网址的全长哈希。也就是说，h（网址）= SHA256（网址）。substr (4)，H（网址）= SHA256（网址）。

假设一个拥有空缓存的客户端访问 example.com/，并看到本地数据库中存在 h(example.com/)。客户端请求哈希前缀 h(example.com/) 的全长哈希，并收到全长哈希 H(example.com/) 以及正缓存到期时间（从现在起 5 分钟）和负缓存到期时间（从现在起 1 小时后）。

5 分钟的正缓存时长会告诉客户端应在此时间内将全长哈希 H(example.com/) 视为不安全，而无需发送其他 hashes.search 请求。5 分钟后，如果客户端再次访问 example.com/，则必须为该前缀 h(example.com/) 发送另一个 hashes.search 请求。客户端应为每个新响应重置哈希前缀的负缓存到期时间。

1 小时的负缓存持续时长会告诉客户端除了 H(example.com/) 外，其他所有共用相同前缀 h(example.com/) 的其他全长哈希在此时间段内被认为是安全的。在 1 小时的时间段内，每个包含 h（网址）= h(example.com/) 的网址都必须被视为安全网址，因此不会产生 hashes.search 请求（假设 H（网址）！= H (example.com/)）。

如果 fullHashes 响应包含零匹配且设置了负缓存到期时间，则客户端不得为给定负缓存时间的任何请求发出任何 hashes.search 请求。

如果 hashes.search 响应包含一个或多个匹配项，则系统仍会为整个响应设置一个负缓存到期时间。在这种情况下，单个完整哈希的缓存到期时间表示客户端必须假设特定完整哈希不安全的时间。在 ThreatHash 缓存持续时间过后，如果请求的网址与缓存中的现有全长哈希相匹配，则客户端必须通过为该哈希前缀发出 hashes.search 请求来刷新全长哈希。在这种情况下，负缓存持续时间不适用。响应的负缓存持续时间仅适用于 hashes.search 响应中不存在的全长哈希。对于响应中不存在的全长哈希，客户端必须避免发出任何 hashes.search 请求，直到缓存时间段结束。