Method: threatListUpdates.fetch

获取最新的威胁列表更新。客户可以一次请求更新多个名单。

HTTP 请求

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据:

JSON 表示法
{
  "client": {
    object (ClientInfo)
  },
  "listUpdateRequests": [
    {
      object (ListUpdateRequest)
    }
  ]
}
字段
client

object (ClientInfo)

客户端元数据。

listUpdateRequests[]

object (ListUpdateRequest)

请求的威胁列表已更新。

响应正文

如果成功,响应正文将包含结构如下的数据:

JSON 表示法
{
  "listUpdateResponses": [
    {
      object (ListUpdateResponse)
    }
  ],
  "minimumWaitDuration": string
}
字段
listUpdateResponses[]

object (ListUpdateResponse)

客户端请求的列表更新。此处的响应数可能少于客户端发送的请求数。例如,如果服务器没有针对特定列表的更新,就会出现这种情况。

minimumWaitDuration

string (Duration format)

在发出任何更新请求之前客户端必须等待的最短时长。如果未设置此字段,则客户端可以根据需要立即更新。

该持续时间以秒为单位,最多包含九个小数位,以“s”结尾。示例:"3.5s"

ListUpdateRequest

单个列表更新请求。

JSON 表示法
{
  "threatType": enum (ThreatType),
  "platformType": enum (PlatformType),
  "threatEntryType": enum (ThreatEntryType),
  "state": string,
  "constraints": {
    object (Constraints)
  }
}
字段
threatType

enum (ThreatType)

列表中显示的条目带来的威胁类型。

platformType

enum (PlatformType)

按列表中显示的条目划分的存在风险的平台类型。

threatEntryType

enum (ThreatEntryType)

列表中显示的条目类型。

state

string (bytes format)

所请求列表的客户端的当前状态(从上次成功的列表更新中收到的加密客户端状态)。

使用 base64 编码的字符串。

constraints

object (Constraints)

与此请求关联的限制条件。

约束条件

此更新的约束条件。

JSON 表示法
{
  "maxUpdateEntries": integer,
  "maxDatabaseEntries": integer,
  "region": string,
  "supportedCompressions": [
    enum (CompressionType)
  ],
  "language": string,
  "deviceLocation": string
}
字段
maxUpdateEntries

integer

条目数的大小上限。更新包含的条目数不会超过此值。此值应为 2**10 到 2**20 之间的 2 的幂。如果为零,则未设置更新大小限制。

maxDatabaseEntries

integer

设置客户端愿意在本地数据库中为指定列表包含的最大条目数。此值应为 2**10 到 2**20 之间的 2 的幂。如果为零,则未设置数据库大小限制。

region

string

请求特定地理位置的列表。如果未设置此政策,服务器可能会根据用户的 IP 地址选择该值。应使用 ISO 3166-1 alpha-2 格式。

supportedCompressions[]

enum (CompressionType)

客户端支持的压缩类型。

language

string

请求特定语言的列表。应使用 ISO 639 alpha-2 格式。

deviceLocation

string

客户端的实际位置,表示为 ISO 31166-1 alpha-2 区域代码。

CompressionType

威胁条目集的压缩方式。

枚举
COMPRESSION_TYPE_UNSPECIFIED 未知。
RAW 未压缩的原始数据。
RICE Rice-Golomb 编码的数据。

ListUpdateResponse

对单个列表的更新。

JSON 表示法
{
  "threatType": enum (ThreatType),
  "threatEntryType": enum (ThreatEntryType),
  "platformType": enum (PlatformType),
  "responseType": enum (ResponseType),
  "additions": [
    {
      object (ThreatEntrySet)
    }
  ],
  "removals": [
    {
      object (ThreatEntrySet)
    }
  ],
  "newClientState": string,
  "checksum": {
    object (Checksum)
  }
}
字段
threatType

enum (ThreatType)

返回其数据的威胁类型。

threatEntryType

enum (ThreatEntryType)

威胁的格式。

platformType

enum (PlatformType)

为其返回数据的平台类型。

responseType

enum (ResponseType)

响应类型。这可能表示收到响应时客户端需要执行某项操作。

additions[]

object (ThreatEntrySet)

要添加到本地威胁类型列表的一组条目。重复此字段,以便在单个响应中发送压缩数据和原始数据的组合。

removals[]

object (ThreatEntrySet)

要从本地威胁类型列表中移除的一组条目。在实践中,此字段为空或恰好包含一个 ThreatEntrySet。

newClientState

string (bytes format)

采用加密格式的新客户端状态。对客户端不透明。

使用 base64 编码的字符串。

checksum

object (Checksum)

客户端状态的预期 SHA256 哈希值;即应用提供的更新后,数据库中存在的所有哈希的排序列表。如果客户端状态与预期状态不符,客户端必须忽略此更新并稍后重试。

ResponseType

发送到客户端的响应类型。

枚举
RESPONSE_TYPE_UNSPECIFIED 未知。
PARTIAL_UPDATE 部分更新将应用于客户端的现有本地数据库。
FULL_UPDATE 完全更新会替换客户端的整个本地数据库。这表示客户端严重过旧,或者系统认为该客户端已损坏。

ThreatEntrySet

应从客户端的本地数据库添加或移除的一组威胁。

JSON 表示法
{
  "compressionType": enum (CompressionType),
  "rawHashes": {
    object (RawHashes)
  },
  "rawIndices": {
    object (RawIndices)
  },
  "riceHashes": {
    object (RiceDeltaEncoding)
  },
  "riceIndices": {
    object (RiceDeltaEncoding)
  }
}
字段
compressionType

enum (CompressionType)

此集中条目的压缩类型。

rawHashes

object (RawHashes)

采用 SHA256 格式的原始条目。

rawIndices

object (RawIndices)

本地列表的原始移除索引。

riceHashes

object (RiceDeltaEncoding)

SHA256 格式的条目的编码 4 字节前缀,使用 Golomb-Rice 编码。哈希值会转换为 uint32,按升序排序,然后进行增量编码并存储为 codingData。

riceIndices

object (RiceDeltaEncoding)

使用 Golomb-Rice 编码进行编码的本地按字典顺序排序的列表索引。用于发送压缩的移除索引。移除索引 (uint32) 按升序排序,然后进行增量编码并存储为 EncodingData。

RawHashes

采用特定前缀长度的哈希格式的未压缩威胁条目。哈希的大小可以是 4 到 32 个字节。大多数哈希为 4 个字节,但某些哈希与热门网址的哈希冲突时会被加长。

用于向不支持压缩的客户端发送 ThreatEntrySet,或向支持压缩的客户端发送非 4 字节哈希时。

JSON 表示法
{
  "prefixSize": integer,
  "rawHashes": string
}
字段
prefixSize

integer

下面编码的每个前缀的字节数。此字段可以是 4(最短前缀)到 32(完整 SHA256 哈希)之间的任意值。

rawHashes

string (bytes format)

这些哈希采用二进制格式,串联成一个长字符串。哈希按字典顺序排序。对于 JSON API 用户,哈希采用 base64 编码。

使用 base64 编码的字符串。

RawIndices

要从本地列表中移除的一组原始索引。

JSON 表示法
{
  "indices": [
    integer
  ]
}
字段
indices[]

integer

要从按字典顺序排序的本地列表中移除的索引。

RiceDeltaEncoding

Rice-Golomb 编码数据。用于发送压缩的 4 字节哈希或压缩的移除索引。

JSON 表示法
{
  "firstValue": string,
  "riceParameter": integer,
  "numEntries": integer,
  "encodedData": string
}
字段
firstValue

string (int64 format)

编码数据中第一个条目的偏移量,或者该单个整数的值(如果只对一个整数进行编码)。如果该字段为空或缺失,则假定为零。

riceParameter

integer

Golomb-Rice 参数,是一个介于 2 到 28 之间的数字。如果 numEntries 为零,则此字段缺失(即零)。

numEntries

integer

在编码数据中进行了增量编码的条目数。如果只对一个整数进行编码,此值将为 0,并且该单个值会存储在 firstValue 中。

encodedData

string (bytes format)

使用 Golomb-Rice 编码器进行编码的已编码增量。

使用 base64 编码的字符串。

校验和

客户端本地数据库的预期状态。

JSON 表示法
{
  "sha256": string
}
字段
sha256

string (bytes format)

客户端状态的 SHA256 哈希值;即数据库中所有哈希值的排序列表。

使用 base64 编码的字符串。