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,按升序排序,然后经过增量编码并存储为 encodedData。

riceIndices

object (RiceDeltaEncoding)

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

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 编码的字符串。