此页面由 Cloud Translation API 翻译。

Package google.security.safebrowsing.v4

索引

SafeBrowsing（接口）
Checksum（消息）
ClientInfo（消息）
CompressionType（枚举）
FetchThreatListUpdatesRequest（消息）
FetchThreatListUpdatesRequest.ListUpdateRequest（消息）
FetchThreatListUpdatesRequest.ListUpdateRequest.Constraints（消息）
FetchThreatListUpdatesResponse（消息）
FetchThreatListUpdatesResponse.ListUpdateResponse（消息）
FetchThreatListUpdatesResponse.ListUpdateResponse.ResponseType（枚举）
FindFullHashesRequest（消息）
FindFullHashesResponse（消息）
FindThreatMatchesRequest（消息）
FindThreatMatchesResponse（消息）
ListThreatListsResponse（消息）
PlatformType（枚举）
RawHashes（消息）
RawIndices（消息）
RiceDeltaEncoding（消息）
ThreatEntry（消息）
ThreatEntryMetadata（消息）
ThreatEntryMetadata.MetadataEntry（消息）
ThreatEntrySet（消息）
ThreatEntryType（枚举）
ThreatInfo（消息）
ThreatListDescriptor（消息）
ThreatMatch（消息）
ThreatType（枚举）

SafeBrowsing

通过 Safe Browsing API，客户端可以对照 Google 持续更新的不安全网络资源列表检查网络资源（最常见的网址）。Safe Browsing API (v4) 包含 Update API 和 Lookup API。

Update API 专为大型客户端而设计，包含 FindFullHashes 和 FetchThreatListUpdates 方法。Update API 要求客户端在本地数据库中维护下载的威胁列表。

首先，客户端与其本地列表进行匹配，以确定给定网络资源的状态（安全或不安全）。最常见的情况是，名单由已列入屏蔽名单的网址表达式的哈希前缀构成。要检查网址，客户端需生成给定网址的哈希值，并检查其本地列表中是否存在前缀冲突；如果找到前缀匹配，客户端将通过 FindFullHashes 方法获取与匹配的哈希前缀相关联的完整哈希值。然后，客户端会将本地完整哈希值与返回的完整哈希值进行比较；若匹配，则表示该网址不安全。

其次，客户端通过 FetchThreatListUpdates 方法获取对本地数据库的更新，该方法会获取客户端的当前状态，并返回更新后的客户端状态以及客户端应该应用到其本地威胁列表的更改。

Lookup API 是为小型客户端设计的，可让它们通过 FindThreatMatch 方法直接将资源与安全浏览威胁列表进行匹配。

使用 Update API 或 Lookup API 的客户端可以获得安全浏览威胁列表的列表，这些列表可通过 ListThreatLists 方法下载。

{-- TRUSTED_THREAT_REPORTER: 受信任的威胁客户端可通过 SubmitThreatReport 方法向 Google 提交报告进行分析。--}

FetchThreatListUpdates

FetchThreatListUpdates
`rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)` 获取最新的威胁列表更新。客户端可以一次请求多个列表的更新。

rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)

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

FindFullHashes

FindFullHashes
`rpc FindFullHashes(FindFullHashesRequest) returns (FindFullHashesResponse)` 查找与所请求的哈希前缀匹配的完整哈希。

rpc FindFullHashes(FindFullHashesRequest) returns (FindFullHashesResponse)

查找与所请求的哈希前缀匹配的完整哈希。

FindThreatMatches

FindThreatMatches
`rpc FindThreatMatches(FindThreatMatchesRequest) returns (FindThreatMatchesResponse)` 查找与安全浏览列表匹配的威胁条目。

rpc FindThreatMatches(FindThreatMatchesRequest) returns (FindThreatMatchesResponse)

查找与安全浏览列表匹配的威胁条目。

ListThreatLists

ListThreatLists
`rpc ListThreatLists(Empty) returns (ListThreatListsResponse)` 列出可供下载的安全浏览威胁列表。

rpc ListThreatLists(Empty) returns (ListThreatListsResponse)

列出可供下载的安全浏览威胁列表。

校验和

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

字段

字段
`sha256`	`bytes` 客户端状态的 SHA256 哈希值；即数据库中出现的所有哈希值的经过排序的列表。

sha256

bytes

客户端状态的 SHA256 哈希值；即数据库中出现的所有哈希值的经过排序的列表。

ClientInfo

与 Safe Browsing API 请求关联的客户端元数据。

字段

字段
`client_id`	`string` 一个客户端 ID，可唯一地标识 Safe Browsing API 的客户端实现。
`client_version`	`string` 客户端实现的版本。

client_id

string

一个客户端 ID，可唯一地标识 Safe Browsing API 的客户端实现。

client_version

string

客户端实现的版本。

CompressionType

威胁条目集的压缩方式。

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

FetchThreatListUpdatesRequest

描述 Safe Browsing API 更新请求。客户端可以在单个请求中请求多个列表的更新。如果服务器没有针对相应列表的更新，服务器可能不会响应所有请求。注意：字段索引 2 未使用。下一步：5

字段

client

ClientInfo

客户端元数据。

list_update_requests[]

ListUpdateRequest

请求的威胁列表会更新。

ListUpdateRequest

单个列表更新请求。

字段
`threat_type`	`ThreatType` 列表中显示的条目所造成的威胁类型。
`platform_type`	`PlatformType` 列表中存在的条目存在风险的平台类型。
`threat_entry_type`	`ThreatEntryType` 列表中显示的条目类型。
`state`	`bytes` 所请求列表的客户端的当前状态（自上次成功列表更新后收到的加密客户端状态）。
`constraints`	`Constraints` 与此请求关联的限制条件。

限制条件

此更新的约束条件。

字段
`max_update_entries`	`int32` 条目数的大小上限。该更新包含的条目数不会超过此值。此值应为 210 到 220 之间的 2 的幂。如果为零，则未设置更新大小限制。
`max_database_entries`	`int32` 设置客户端愿意在本地数据库中为指定列表包含的条目数上限。此值应为 210 到 220 之间的 2 的幂。如果为零，则未设置数据库大小限制。
`region`	`string` 请求特定地理位置的列表。如果未设置，服务器可能会根据用户的 IP 地址选择该值。要求采用 ISO 3166-1 alpha-2 格式。
`supported_compressions[]`	`CompressionType` 客户端支持的压缩类型。
`language`	`string` 请求特定语言的列表。要求采用 ISO 639 alpha-2 格式。
`device_location`	`string` 客户端的实际位置，表示为 ISO 31166-1 alpha-2 区域代码。

FetchThreatListUpdatesResponse

字段

字段
`list_update_responses[]`	`ListUpdateResponse` 客户端请求的列表更新。此处的响应数可能少于客户端发送的请求数。例如，如果服务器没有针对特定列表的更新，就会出现这种情况。
`minimum_wait_duration`	`Duration` 在发出任何更新请求之前客户端必须等待的最短时间。如果未设置此字段，则客户端可能会随时进行更新。

list_update_responses[]

ListUpdateResponse

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

minimum_wait_duration

Duration

在发出任何更新请求之前客户端必须等待的最短时间。如果未设置此字段，则客户端可能会随时进行更新。

ListUpdateResponse

对单个列表的更新。

字段
`threat_type`	`ThreatType` 返回其数据的威胁类型。
`threat_entry_type`	`ThreatEntryType` 威胁的格式。
`platform_type`	`PlatformType` 要为其返回数据的平台类型。
`response_type`	`ResponseType` 响应的类型。这可能表示收到响应时客户端需要执行操作。
`additions[]`	`ThreatEntrySet` 要添加到本地威胁类型列表的一组条目。重复上述步骤，以便在单个响应中发送压缩数据和原始数据的组合。
`removals[]`	`ThreatEntrySet` 要从本地威胁类型列表中移除的一组条目。实际上，此字段为空或正好包含一个 ThreatEntrySet。
`new_client_state`	`bytes` 采用加密格式的新客户端状态。对客户端不透明。
`checksum`	`Checksum` 客户端状态的预期 SHA256 哈希；也就是应用提供的更新后，数据库中出现的所有哈希的排序列表。如果客户端状态与预期状态不符，客户端必须忽略此更新并稍后重试。

ResponseType

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

枚举
`RESPONSE_TYPE_UNSPECIFIED`	未知。
`PARTIAL_UPDATE`	部分更新将应用于客户端的现有本地数据库。
`FULL_UPDATE`	完全更新会替换客户端的整个本地数据库。这意味着客户端严重已过时或客户端已损坏。

FindFullHashesRequest

请求返回与提供的哈希前缀匹配的完整哈希。

字段
`client`	`ClientInfo` 客户端元数据。
`client_states[]`	`bytes` 每个客户端本地威胁列表的当前客户端状态。
`threat_info`	`ThreatInfo` 要检查的列表和哈希。
`api_client`	`ClientInfo` 与基于客户端实现构建的更高级别 API 的调用方相关联的客户端元数据。

FindFullHashesResponse

字段

字段
`matches[]`	`ThreatMatch` 与所请求前缀匹配的完整哈希。
`minimum_wait_duration`	`Duration` 客户端在发出任何查找哈希请求之前必须等待的最短时长。如果未设置此字段，客户端可以根据需要立即发出请求。
`negative_cache_duration`	`Duration` 对于与威胁列表不匹配的所请求实体，将响应缓存多长时间。

matches[]

ThreatMatch

与所请求前缀匹配的完整哈希。

minimum_wait_duration

Duration

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

negative_cache_duration

Duration

对于与威胁列表不匹配的所请求实体，将响应缓存多长时间。

FindThreatMatchesRequest

请求根据列表检查条目。

字段

client

ClientInfo

客户端元数据。

threat_info

ThreatInfo

要检查是否存在匹配的列表和条目。

FindThreatMatchesResponse

字段

字段
`matches[]`	`ThreatMatch` 威胁列表一致。

matches[]

ThreatMatch

威胁列表一致。

ListThreatListsResponse

字段

字段
`threat_lists[]`	`ThreatListDescriptor` 可供客户端下载的列表。

threat_lists[]

ThreatListDescriptor

可供客户端下载的列表。

PlatformType

平台类型。

枚举
`PLATFORM_TYPE_UNSPECIFIED`	未知平台。
`WINDOWS`	对 Windows 构成了威胁。
`LINUX`	对 Linux 构成了威胁。
`ANDROID`	对 Android 构成了威胁。
`OSX`	对 OS X 构成威胁。
`IOS`	对 iOS 构成威胁。
`ANY_PLATFORM`	对至少一个指定平台构成威胁。
`ALL_PLATFORMS`	对所有定义的平台构成威胁。
`CHROME`	Chrome 遭到了威胁。

RawHashes

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

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

字段

字段
`prefix_size`	`int32` 下面编码的每个前缀的字节数。此字段可以是从 4（最短前缀）到 32（完整 SHA256 哈希）的任何值。
`raw_hashes`	`bytes` 这些哈希采用二进制格式，串联成一个长字符串。哈希值按字典顺序排序。对于 JSON API 用户，哈希采用 base64 编码。

prefix_size

int32

下面编码的每个前缀的字节数。此字段可以是从 4（最短前缀）到 32（完整 SHA256 哈希）的任何值。

raw_hashes

bytes

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

RawIndices

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

字段

字段
`indices[]`	`int32` 要从按字典顺序排序的本地列表中移除的索引。

indices[]

int32

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

RiceDeltaEncoding

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

字段
`first_value`	`int64` 编码数据中第一个条目的偏移量，或者，如果仅编码了一个整数，则值为该单个整数的值。如果该字段为空或缺失，则假定为零。
`rice_parameter`	`int32` Golomb-Rice 参数，是一个介于 2 到 28 之间的数字。如果 `num_entries` 为零，则此字段缺失（即零）。
`num_entries`	`int32` 编码数据中经过增量编码的条目数。如果只对一个整数进行编码，此值将为 0，并且该单个值将存储在 `first_value` 中。
`encoded_data`	`bytes` 使用 Golomb-Rice 编码器编码的已编码增量。

ThreatEntry

单个威胁；例如，恶意网址或其哈希表示。您只能设置其中一个字段。

字段

字段
`hash`	`bytes` 哈希前缀，由 SHA256 哈希的最高 4-32 个字节组成。此字段采用二进制格式。对于 JSON 请求，哈希采用 base64 编码。
`url`	`string` 网址。
`digest`	`bytes` 可执行文件的摘要，采用 SHA256 格式。该 API 支持二进制摘要和十六进制摘要。对于 JSON 请求，摘要采用 base64 编码。

hash

bytes

哈希前缀，由 SHA256 哈希的最高 4-32 个字节组成。此字段采用二进制格式。对于 JSON 请求，哈希采用 base64 编码。

url

string

网址。

digest

bytes

可执行文件的摘要，采用 SHA256 格式。该 API 支持二进制摘要和十六进制摘要。对于 JSON 请求，摘要采用 base64 编码。

ThreatEntryMetadata

与特定威胁条目关联的元数据。客户端应知道与每个威胁类型关联的元数据键值对。

字段

entries[]

MetadataEntry

元数据条目。

MetadataEntry

单个元数据条目。

字段

key

bytes

元数据条目键。对于 JSON 请求，密钥采用 base64 编码。

value

bytes

元数据条目值。对于 JSON 请求，该值采用 base64 编码。

ThreatEntrySet

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

字段
`compression_type`	`CompressionType` 此集中条目的压缩类型。
`raw_hashes`	`RawHashes` 采用 SHA256 格式的原始条目。
`raw_indices`	`RawIndices` 本地列表的原始移除索引。
`rice_hashes`	`RiceDeltaEncoding` SHA256 格式条目的编码 4 字节前缀，使用 Golomb-Rice 编码。这些哈希值会转换为 uint32，按升序排序，然后进行增量编码并存储为 encoded_data。
`rice_indices`	`RiceDeltaEncoding` 使用 Golomb-Rice 编码且按字典顺序排序的本地编码列表索引。用于发送经过压缩的移除索引。移除索引 (uint32) 按升序排序，然后进行增量编码并存储为 encoded_data。

ThreatEntryType

造成威胁的条目类型。威胁列表是单个类型的条目的集合。

枚举
`THREAT_ENTRY_TYPE_UNSPECIFIED`	未指定。
`URL`	网址。
`EXECUTABLE`	可执行程序。

ThreatInfo

有关客户在检查威胁列表中的匹配时提交的一个或多个威胁的信息。

字段
`threat_types[]`	`ThreatType` 要检查的威胁类型。
`platform_types[]`	`PlatformType` 要检查的平台类型。
`threat_entry_types[]`	`ThreatEntryType` 要检查的条目类型。
`threat_entries[]`	`ThreatEntry` 要检查的威胁条目。

ThreatListDescriptor

描述单个威胁列表。列表由三个参数定义：威胁的类型、威胁的目标平台类型以及列表中的条目类型。

字段

字段
`threat_type`	`ThreatType` 列表条目提出的威胁类型。
`platform_type`	`PlatformType` 列表条目定位的平台类型。
`threat_entry_type`	`ThreatEntryType` 列表中包含的条目类型。

threat_type

ThreatType

列表条目提出的威胁类型。

platform_type

PlatformType

列表条目定位的平台类型。

threat_entry_type

ThreatEntryType

列表中包含的条目类型。

ThreatMatch

如果检测到“安全浏览”威胁列表中的某个威胁条目，则视为匹配项。

字段
`threat_type`	`ThreatType` 与此威胁匹配的威胁类型。
`platform_type`	`PlatformType` 与此威胁匹配的平台类型。
`threat_entry_type`	`ThreatEntryType` 与此威胁匹配的威胁条目类型。
`threat`	`ThreatEntry` 与此威胁匹配的威胁。
`threat_entry_metadata`	`ThreatEntryMetadata` 与此威胁相关联的可选元数据。
`cache_duration`	`Duration` 所返回匹配项的缓存期限。客户端缓存此响应的时长不得超过此上限，以避免误报。

ThreatType

威胁类型。

枚举
`THREAT_TYPE_UNSPECIFIED`	未知。
`MALWARE`	恶意软件威胁类型。
`SOCIAL_ENGINEERING`	社会工程学威胁类型。
`UNWANTED_SOFTWARE`	垃圾软件威胁类型。
`POTENTIALLY_HARMFUL_APPLICATION`	可能有害的应用威胁类型。