- HTTP 请求
- 请求正文
- 响应正文
- ListUpdateRequest
- 限制条件
- CompressionType
- ListUpdateResponse
- ResponseType
- ThreatEntrySet
- RawHashes
- RawIndices
- RiceDeltaEncoding
- 校验和
获取最新的威胁列表更新。客户可以一次请求更新多个名单。
HTTP 请求
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch
网址采用 gRPC 转码语法。
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 | |
---|---|
{ "client": { object ( |
字段 | |
---|---|
client |
客户端元数据。 |
listUpdateRequests[] |
请求的威胁列表已更新。 |
响应正文
如果成功,响应正文将包含结构如下的数据:
JSON 表示法 | |
---|---|
{
"listUpdateResponses": [
{
object ( |
字段 | |
---|---|
listUpdateResponses[] |
客户端请求的列表更新。此处的响应数可能少于客户端发送的请求数。例如,如果服务器没有针对特定列表的更新,就会出现这种情况。 |
minimumWaitDuration |
在发出任何更新请求之前客户端必须等待的最短时长。如果未设置此字段,则客户端可以根据需要立即更新。 该持续时间以秒为单位,最多包含九个小数位,以“ |
ListUpdateRequest
单个列表更新请求。
JSON 表示法 | |
---|---|
{ "threatType": enum ( |
字段 | |
---|---|
threatType |
列表中显示的条目带来的威胁类型。 |
platformType |
按列表中显示的条目划分的存在风险的平台类型。 |
threatEntryType |
列表中显示的条目类型。 |
state |
所请求列表的客户端的当前状态(从上次成功的列表更新中收到的加密客户端状态)。 使用 base64 编码的字符串。 |
constraints |
与此请求关联的限制条件。 |
约束条件
此更新的约束条件。
JSON 表示法 | |
---|---|
{
"maxUpdateEntries": integer,
"maxDatabaseEntries": integer,
"region": string,
"supportedCompressions": [
enum ( |
字段 | |
---|---|
maxUpdateEntries |
条目数的大小上限。更新包含的条目数不会超过此值。此值应为 2**10 到 2**20 之间的 2 的幂。如果为零,则未设置更新大小限制。 |
maxDatabaseEntries |
设置客户端愿意在本地数据库中为指定列表包含的最大条目数。此值应为 2**10 到 2**20 之间的 2 的幂。如果为零,则未设置数据库大小限制。 |
region |
请求特定地理位置的列表。如果未设置此政策,服务器可能会根据用户的 IP 地址选择该值。应使用 ISO 3166-1 alpha-2 格式。 |
supportedCompressions[] |
客户端支持的压缩类型。 |
language |
请求特定语言的列表。应使用 ISO 639 alpha-2 格式。 |
deviceLocation |
客户端的实际位置,表示为 ISO 31166-1 alpha-2 区域代码。 |
CompressionType
威胁条目集的压缩方式。
枚举 | |
---|---|
COMPRESSION_TYPE_UNSPECIFIED |
未知。 |
RAW |
未压缩的原始数据。 |
RICE |
Rice-Golomb 编码的数据。 |
ListUpdateResponse
对单个列表的更新。
JSON 表示法 | |
---|---|
{ "threatType": enum ( |
字段 | |
---|---|
threatType |
返回其数据的威胁类型。 |
threatEntryType |
威胁的格式。 |
platformType |
为其返回数据的平台类型。 |
responseType |
响应类型。这可能表示收到响应时客户端需要执行某项操作。 |
additions[] |
要添加到本地威胁类型列表的一组条目。重复此字段,以便在单个响应中发送压缩数据和原始数据的组合。 |
removals[] |
要从本地威胁类型列表中移除的一组条目。在实践中,此字段为空或恰好包含一个 ThreatEntrySet。 |
newClientState |
采用加密格式的新客户端状态。对客户端不透明。 使用 base64 编码的字符串。 |
checksum |
客户端状态的预期 SHA256 哈希值;即应用提供的更新后,数据库中存在的所有哈希的排序列表。如果客户端状态与预期状态不符,客户端必须忽略此更新并稍后重试。 |
ResponseType
发送到客户端的响应类型。
枚举 | |
---|---|
RESPONSE_TYPE_UNSPECIFIED |
未知。 |
PARTIAL_UPDATE |
部分更新将应用于客户端的现有本地数据库。 |
FULL_UPDATE |
完全更新会替换客户端的整个本地数据库。这表示客户端严重过旧,或者系统认为该客户端已损坏。 |
ThreatEntrySet
应从客户端的本地数据库添加或移除的一组威胁。
JSON 表示法 | |
---|---|
{ "compressionType": enum ( |
字段 | |
---|---|
compressionType |
此集中条目的压缩类型。 |
rawHashes |
采用 SHA256 格式的原始条目。 |
rawIndices |
本地列表的原始移除索引。 |
riceHashes |
SHA256 格式的条目的编码 4 字节前缀,使用 Golomb-Rice 编码。哈希值会转换为 uint32,按升序排序,然后进行增量编码并存储为 codingData。 |
riceIndices |
使用 Golomb-Rice 编码进行编码的本地按字典顺序排序的列表索引。用于发送压缩的移除索引。移除索引 (uint32) 按升序排序,然后进行增量编码并存储为 EncodingData。 |
RawHashes
采用特定前缀长度的哈希格式的未压缩威胁条目。哈希的大小可以是 4 到 32 个字节。大多数哈希为 4 个字节,但某些哈希与热门网址的哈希冲突时会被加长。
用于向不支持压缩的客户端发送 ThreatEntrySet,或向支持压缩的客户端发送非 4 字节哈希时。
JSON 表示法 | |
---|---|
{ "prefixSize": integer, "rawHashes": string } |
字段 | |
---|---|
prefixSize |
下面编码的每个前缀的字节数。此字段可以是 4(最短前缀)到 32(完整 SHA256 哈希)之间的任意值。 |
rawHashes |
这些哈希采用二进制格式,串联成一个长字符串。哈希按字典顺序排序。对于 JSON API 用户,哈希采用 base64 编码。 使用 base64 编码的字符串。 |
RawIndices
要从本地列表中移除的一组原始索引。
JSON 表示法 | |
---|---|
{ "indices": [ integer ] } |
字段 | |
---|---|
indices[] |
要从按字典顺序排序的本地列表中移除的索引。 |
RiceDeltaEncoding
Rice-Golomb 编码数据。用于发送压缩的 4 字节哈希或压缩的移除索引。
JSON 表示法 | |
---|---|
{ "firstValue": string, "riceParameter": integer, "numEntries": integer, "encodedData": string } |
字段 | |
---|---|
firstValue |
编码数据中第一个条目的偏移量,或者该单个整数的值(如果只对一个整数进行编码)。如果该字段为空或缺失,则假定为零。 |
riceParameter |
Golomb-Rice 参数,是一个介于 2 到 28 之间的数字。如果 |
numEntries |
在编码数据中进行了增量编码的条目数。如果只对一个整数进行编码,此值将为 0,并且该单个值会存储在 |
encodedData |
使用 Golomb-Rice 编码器进行编码的已编码增量。 使用 base64 编码的字符串。 |
校验和
客户端本地数据库的预期状态。
JSON 表示法 | |
---|---|
{ "sha256": string } |
字段 | |
---|---|
sha256 |
客户端状态的 SHA256 哈希值;即数据库中所有哈希值的排序列表。 使用 base64 编码的字符串。 |