概览
Update API 可让您的客户端应用下载经过哈希处理的安全浏览列表版本， 存储在本地数据库中然后，您可以在本地检查网址。只有在本地数据库中找到匹配项时，客户端才需要向安全浏览服务器发送请求，以验证网址是否包含在安全浏览列表中。
在使用 Update API 之前，您需要设置本地数据库。安全浏览提供了一个 Go 软件包，可供您快速上手使用。有关详情，请参阅“数据库设置”部分 本地数据库。
更新本地数据库
要及时了解最新信息，客户端必须定期更新其本地数据库中的安全浏览列表。为了节省带宽，客户端会下载网址的哈希前缀，而不是 原始网址。例如，如果“www.badurl.com/”被列入了安全浏览列表，那么客户端会下载 该网址的 SHA256 哈希前缀，而不是网址本身。在大多数情况下，哈希前缀的长度为 4 个字节，这意味着在压缩之前下载单个列表条目的平均带宽费用为 4 个字节。
要更新本地数据库中的安全浏览列表，请将 HTTP POST 请求发送到
threatListUpdates.fetch
方法：
- HTTP
POST请求包含要更新列表的名称以及考虑内存和带宽限制的各种客户端约束。 - HTTP
POST响应会返回完整更新或部分更新。响应还可以返回最短等待时长。
示例： ThreatListUpdates.fetch
HTTP POST 请求
在以下示例中，系统会请求更新单个安全浏览列表。
请求标头
请求标头包含请求网址和内容类型。请务必替换您的 API
API_KEY 对应的键。
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
请求正文
请求正文包含客户端信息（ID 和版本）和更新信息（列表名称、列表状态和客户端约束）。如需了解详情，请参阅 threatListUpdates.fetch 请求正文以及代码示例后面的说明。
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "listUpdateRequests": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "state": "Gg4IBBADIgYQgBAiAQEoAQ==", "constraints": { "maxUpdateEntries": 2048, "maxDatabaseEntries": 4096, "region": "US", "supportedCompressions": ["RAW"] } }] }
客户端信息
clientID 和 clientVersion 字段应用于唯一标识客户端实现，而非单个用户。（客户端信息用于服务器端日志记录。您可以为客户端 ID 选择任何名称，但我们建议您选择一个能代表客户端真实身份的名称，例如您的公司名称，应采用一个单词，全部采用小写字母。
安全浏览列表
threatType、platformType 和 threatEntryType 字段组合用于标识（命名）安全浏览名单。在此示例中，标识了一个列表：
恶意软件/窗口/网址。在发送请求之前，请确保您指定的类型组合有效
（请参阅安全浏览列表）。
客户端状态
state 字段包含安全浏览列表的当前客户端状态。
（客户端状态在 threatListUpdates.fetch 响应的 newClientState 字段中返回。）
对于初始更新，请将 state 字段留空。
尺寸限制
maxUpdateEntries 字段指定客户端可以管理的更新总数（在此示例中为 2048）。maxDatabaseEntries 字段指定本地
数据库可以管理（以 4096 为例）。客户端应设置大小限制
以保护内存和带宽限制，并防止
增长。如需更多信息
（请参阅 Update Constraints）。
支持压缩
supportedCompressions 字段列出了客户端支持的压缩类型。在
例如，客户端仅支持未压缩的原始数据。但安全浏览支持其他压缩类型（请参阅压缩）。
HTTP POST 响应
在此示例中，响应使用 请求的压缩类型。
响应标头
响应标头包含 HTTP 状态代码和内容类型。收到 HTTP/200 以外的状态代码的客户端必须进入退避模式 （请参阅请求频率）。
HTTP/1.1 200 OK Content-Type: application/json
响应正文
响应正文包含更新信息（列表名称、响应类型、要应用于本地数据库的添加和移除项、新的客户端状态以及校验和）。在该示例中，响应还包含最短等待时长。有关 请参阅 threatListUpdates.fetch 响应正文 以及相应代码示例的说明。
{
"listUpdateResponses": [{
"threatType": "MALWARE",
"threatEntryType": "URL",
"platformType": "WINDOWS",
"responseType" : "PARTIAL_UPDATE",
"additions": [{
"compressionType": "RAW",
"rawHashes": {
"prefixSize": 4,
"rawHashes": "rnGLoQ=="
}
}],
"removals": [{
"compressionType": "RAW",
"rawIndices": {
"indices": [0, 2, 4]
}
}],
"newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
"checksum": {
"sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
}
}],
"minimumWaitDuration": "593.440s"
}数据库更新
responseType 字段将指示部分更新或完全更新。在该示例中，返回了部分更新，因此响应包括添加和删除项。可能有多组添加项，但只有一组删除项（请参阅数据库更新）。
新的客户端状态
newClientState 字段包含新更新的安全浏览列表的新客户端状态。客户端必须为后续更新请求保存新的客户端状态（threatListUpdates.fetch 请求中的 state 字段或 fullHashes.find 请求中的 clientStates 字段）。
校验和
校验和可让客户端验证本地数据库未遭受任何损坏。如果
校验和不匹配，客户端必须清除数据库，并重新发出一个更新
state 字段。但是，在这种情况下，客户端仍必须遵循更新的时间间隔（请参阅请求频率）。
最短等待时长
minimumWaitDuration 字段表示客户端必须等待 593.44 秒（9.89 分钟）后才能发送其他更新请求。请注意，等待期不一定包含
响应（请参阅请求频率）。
检查网址
要检查某个网址是否在安全浏览列表中，客户端必须先计算哈希值和哈希值 网址的前缀（请参阅网址和哈希处理）。然后，客户端会查询本地数据库以确定是否存在匹配。如果哈希前缀 是 本地数据库中不存在，则该网址被视为安全网址（而非 浏览列表）。
如果本地数据库中存在哈希前缀（哈希前缀冲突）， 客户端必须将哈希前缀发送到安全浏览服务器进行验证。 服务器将返回包含指定哈希前缀的所有完整 SHA 256 哈希。 如果其中一个完整长度的哈希值与相关网址的完整长度哈希值匹配， 那么系统会将该网址视为不安全的网址如果所有完整长度的哈希值都与完整长度的哈希值不匹配 则该网址会被视为安全。
Google 绝不会了解您正在检查的网址。Google 确实会学习网址的哈希前缀，但哈希前缀不会提供有关实际网址的大量信息。
要检查某个网址是否在安全浏览列表中，请将 HTTP POST 请求发送到
fullHashes.find
方法：
- HTTP
POST请求最多可包含 500 个威胁条目。 - HTTP
POST请求包含要检查的网址的哈希前缀。建议客户将多个威胁条目批量处理到单个请求中，以降低带宽用量。 - HTTP
POST响应会返回匹配的全长哈希值以及正负缓存时长。响应还可以返回最短等待时长。
示例：fullHashes.find
HTTP POST 请求
在以下示例中，将发送两个安全浏览列表的名称和三个哈希前缀进行比较和验证。
请求标头
请求标头包含请求网址和内容类型。请务必将
您在网址中为 API_KEY 设置的 API 密钥。
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
请求正文
请求正文包含客户端信息（ID 和版本）、客户端状态以及威胁信息（列表名称和哈希前缀）。对于 JSON 请求，哈希前缀 以 base64 编码形式发送。 有关详情，请参阅 fullHashes.find 请求正文 以及相应代码示例的说明。
{
"client": {
"clientId": "yourcompanyname",
"clientVersion": "1.5.2"
},
"clientStates": [
"ChAIARABGAEiAzAwMSiAEDABEAE=",
"ChAIAhABGAEiAzAwMSiAEDABEOgH"
],
"threatInfo": {
"threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
"platformTypes": ["WINDOWS"],
"threatEntryTypes": ["URL"],
"threatEntries": [
{"hash": "WwuJdQ=="},
{"hash": "771MOg=="},
{"hash": "5eOrwQ=="}
]
}
}客户端信息
clientID 和 clientVersion 字段应用于唯一标识客户端实现，而非单个用户。（客户端信息用于服务器端日志记录。您可为
但我们建议您选择一个可代表该客户端真实身份的名称，例如
公司名称（全部为一个字词，所有字母均采用小写形式）。
所有客户端状态
clientStates 字段包含所有安全浏览列表的客户端状态，
客户端本地数据库（客户端状态在newClientState
threatListUpdates.fetch 响应。）
安全浏览列表
threatTypes、platformTypes和threatEntryTypes
字段组合来标识（命名）
浏览列表。在该示例中，标识了两个列表：MALWARE/WINDOWS/网址 和
SOCIAL_ENGINEERING/WINDOWS/网址。在发送请求之前，请确保您所用的类型组合了
（请参阅安全浏览列表）。
威胁哈希前缀
威胁条目数组包含您要检查的网址的哈希前缀。
hash 字段必须包含本地数据库中存在的确切哈希前缀。对于
例如，如果本地哈希前缀为 4 个字节，则威胁条目的长度必须为 4 个字节。如果
本地哈希前缀已加长为 7 字节，则威胁条目的长度必须为 7 字节。
在此示例中，请求包含三个哈希前缀。系统会比较这三个前缀 来确定是否存在匹配的完整长度哈希。
注意：Update API 和 fullHashes.find 方法应始终使用 hash 字段，
一律不使用 URL 字段（请参阅 ThreatEntry）。
HTTP POST 响应
在以下示例中，响应会返回匹配的数据（这些数据按安全浏览列表进行整理）， 以及缓存和等待时长
响应标头
响应标头包含 HTTP 状态代码 和内容类型收到 HTTP/200 以外的状态代码的客户端必须退避（请参阅 请求频率）。
HTTP/1.1 200 OK Content-Type: application/json
响应正文
响应正文包括匹配信息（列表名称和完整哈希、 元数据（如果有）和缓存时长）。在该示例中，响应正文还包含最短等待时长。如需了解详情，请参阅 fullHashes.find 响应正文以及代码示例后面的说明。
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4=" }, "threatEntryMetadata": { "entries": [{ "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==", // base64-encoded "malware_threat_type" "value": "TEFORElORw==" // base64-encoded "LANDING" }] }, "cacheDuration": "300.000s" }, { "threatType": "SOCIAL_ENGINEERING", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA=" }, "threatEntryMetadata": { "entries": [] }, "cacheDuration": "300.000s" }], "minimumWaitDuration": "300.000s", "negativeCacheDuration": "300.000s" }
配对
Matches 对象会返回两个哈希前缀的匹配完整长度哈希。网址 则视为不安全。未找到与第三个哈希前缀匹配的内容，因此不会返回任何内容；则该哈希前缀对应的网址会被视为安全网址。
请注意，此示例将一个完整长度的哈希与一个哈希前缀进行匹配；但有可能 映射到同一哈希前缀的多个完整哈希。
元数据
threatEntryMetadata 字段为选填字段，提供有关威胁的更多信息
匹配。目前，MALWARE/WINDOWS/URL 安全浏览名单提供元数据（请参阅元数据）。
缓存时长
cacheDuration 和 negativeCacheDuration 字段指示哈希必须被视为不安全或安全的时长（请参阅缓存）。
最短等待时长
minimumWaitDuration 字段表示客户端必须等待 300 秒（5 分钟）才能发送另一个 fullHashes 请求。请注意，响应中不一定包含等待期
（请参阅请求频率）。