本地数据库

本文档适用于以下方法:Update API (v4)threatListUpdates.fetch

数据库设置

使用 Update API 的客户端必须设置本地数据库,并首次下载要使用的安全浏览列表。为此,您可以构建和部署 safebrowsing Go 软件包(或使用软件包为您自己的实现建模)。如需了解详情,请参阅 https://github.com/google/safebrowsing/

数据库更新

为确保防范最新的威胁,强烈建议客户端使用 threatListUpdates.fetch 方法定期更新其本地安全浏览列表。 threatListUpdates.fetch 请求会指定要更新的列表。如果客户端有内存或带宽限制,它们还可以使用该请求设置更新限制(请参阅更新限制)。 threatListUpdates.fetch 响应会针对每个列表返回完全更新或部分更新,如下所述。

完整更新

当客户端将 threatListUpdates.fetch 请求中的 state 字段留空或服务器确定需要完整更新时,系统会返回完整更新。对于完整更新,仅返回 addition。客户端应先清除本地数据库,然后再应用更新和执行验证检查

空状态

当客户端发送初始请求获取列表时,系统将返回完整更新。在这种情况下,请求中的 state 字段留空(因为没有值可以提供),并且响应中的 newClientState 字段会返回本地列表的初始状态。如果客户端故意在后续请求中将 state 字段留空,系统也会返回完整更新。这将强制进行完整更新,并在响应的 newClientState 字段中返回新状态。

服务器决策

有时,如果客户端只请求了部分更新,安全浏览服务器会返回完整更新。如果客户端最初下载小版本的列表,然后更新为较大版本的列表,就可能会发生这种情况;服务器只会返回包含整个列表的完整更新。如果客户端长时间未下载数据并请求部分更新,也可能会发生这种情况;服务器同样只会返回包含整个列表的完整更新。

部分更新

当客户端为 threatListUpdates.fetch 请求中的 state 字段提供值时,系统会返回部分更新(如上文所述,服务器确定需要完全更新时除外)。对于部分更新,系统会返回添加操作移除操作。客户端会更新本地数据库中的列表(先应用移除操作,然后再执行添加操作),然后执行验证检查

添加

添加的内容是应添加到本地数据库的 SHA256 哈希前缀。绝大多数哈希前缀的长度都是 4 个字节,但有些哈希前缀的长度可能介于 4 到 32 个字节之间。 因此,可能会返回多组加法;例如,一组包含 4 字节前缀,另一组包含 5 字节前缀。

如果客户端支持压缩,则可使用 Rice 压缩来压缩响应。但是,只有 4 字节的哈希前缀会被压缩。较长的哈希前缀始终以未压缩的原始格式发送(请参阅压缩)。

移除

移除操作是按字典顺序排序的客户端数据库中从零开始的索引,指向应从本地数据库中移除的条目。只会返回一组移除操作。

如果客户端支持压缩,则会返回“大米哈希值”和“大米索引”。如果不支持压缩,会返回“原始哈希值”和“原始索引”(请参阅压缩)。

验证检查

当返回 threatListUpdates.fetch 响应(包括完全更新或部分更新)时,客户端应执行验证检查。

客户端首先会更新本地数据库中的列表(先应用移除,然后再添加)。然后,客户端会计算(按字典顺序排序的)本地列表的 SHA256 哈希值,并将其与响应中返回的校验和进行比较。如果这两个值相等,则安全浏览列表会被视为“正确”。

如果这两个值不相等,系统就会将安全浏览列表视为“已损坏”。客户端必须从数据库中清除该列表,并重新发出第二次更新(将 state 字段设为空字符串);这将强制执行完整更新并返回全新的列表和状态。