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