Package google.security.safebrowsing.v5alpha1

索引

• SafeBrowsing（接口）
• BatchGetHashListsRequest（消息）
• BatchGetHashListsResponse（消息）
• FullHash（消息）
• FullHash.FullHashDetail（消息）
• GetHashListRequest（消息）
• HashList（消息）
• HashListMetadata（消息）
• HashListMetadata.HashLength（枚举）
• LikelySafeType（枚举）
• ListHashListsRequest（消息）
• ListHashListsResponse（消息）
• RiceDeltaEncoded128Bit（消息）
• RiceDeltaEncoded256Bit（消息）
• RiceDeltaEncoded32Bit（消息）
• RiceDeltaEncoded64Bit（消息）
• SearchHashesRequest（消息）
• SearchHashesResponse（消息）
• SearchUrlsRequest（消息）
• SearchUrlsResponse（消息）
• SizeConstraints（消息）
• ThreatAttribute（枚举）
• ThreatType（枚举）
• ThreatUrl（消息）

SafeBrowsing

借助安全浏览 API，客户端可以根据 Google 持续更新的不安全网络资源列表检查网络资源（最常见的是网址）。

BatchGetHashLists
rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse) 一次获取多个哈希列表。 客户端通常需要获取多个哈希列表。与多次使用常规的 Get 方法相比，此方法是首选方法。 这是 https://google.aip.dev/231 中定义的标准批量 Get 方法，HTTP 方法也是 GET。

GetHashList
rpc GetHashList(GetHashListRequest) returns (HashList) 获取哈希列表的最新内容。哈希列表可以是威胁列表，也可以是非威胁列表，例如全球缓存。 这是 https://google.aip.dev/131 中定义的标准 Get 方法，HTTP 方法也是 GET。

ListHashLists
rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse) 列出哈希列表。 在 V5 API 中，Google 绝不会移除此方法曾经返回的哈希列表。这样，客户端就可以跳过使用此方法，只需对所需的所有哈希列表进行硬编码。 这是 https://google.aip.dev/132 中定义的标准 List 方法，HTTP 方法为 GET。

SearchHashes
rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse) 搜索与指定前缀匹配的完整哈希。 这是 https://google.aip.dev/136 中定义的自定义方法（自定义方法是指在 Google 的一般 API 开发命名规范中具有自定义名称的方法；它不是指使用自定义 HTTP 方法）。

SearchUrls
rpc SearchUrls(SearchUrlsRequest) returns (SearchUrlsResponse) 搜索与已知威胁匹配的网址。系统会检查每个网址及其主机后缀和路径前缀表达式（深度有限）。这意味着，响应可能包含未包含在请求中但属于所请求网址的表达式的网址。

BatchGetHashListsRequest

同时获取多个哈希列表的请求。

字段
names[]	string 必需。特定哈希列表的名称。该列表可以是威胁列表，也可以是全局缓存。名称不得包含重复项；如果包含重复项，客户端将收到错误。
version[]	bytes 客户端已有的哈希列表的版本。如果客户端是首次提取哈希列表，则应将此字段留空。否则，客户端应提供之前从服务器收到的版本。客户端不得操纵这些字节。 客户端无需按与相应列表名称相同的顺序发送版本。客户端在请求中发送的版本数量可能少于或多于名称数量。不过，客户端不得发送对应于同一名称的多个版本；如果这样做，客户端会收到错误。 历史记录：在 API 的 V4 版本中，此方法称为 states；现在为了清晰起见，已重命名为 version。
size_constraints	SizeConstraints 每个列表的大小限制。如果省略，则表示没有限制。请注意，此处的大小是指每个列表的大小，而不是所有列表的总大小。

BatchGetHashListsResponse

包含多个哈希列表的响应。

字段
hash_lists[]	HashList 哈希列表，按请求中给定的顺序排列。

FullHash

通过一个或多个匹配项识别出的完整哈希。

字段
full_hash	bytes 匹配的完整哈希。这是 SHA256 哈希值。长度将正好为 32 字节。
full_hash_details[]	FullHashDetail 无序列表。一个重复字段，用于标识与此完整哈希相关的信息。

FullHashDetail

有关匹配的完整哈希的详细信息。

关于向前兼容性的重要说明：服务器可能会随时添加新的威胁类型和威胁属性；这些添加项被视为次要版本更改。根据 Google 的政策，API 中不会公开次要版本号（有关版本控制政策，请参阅 https://cloud.google.com/apis/design/versioning），因此客户端必须准备好接收包含 ThreatType 枚举值或被客户端视为无效的 ThreatAttribute 枚举值的 FullHashDetail 消息。因此，客户端有责任检查所有 ThreatType 和 ThreatAttribute 枚举值的有效性；如果任何值被视为无效，客户端必须忽略整个 FullHashDetail 消息。

字段
threat_type	ThreatType 威胁类型。此字段不得为空。
attributes[]	ThreatAttribute 无序列表。有关这些完整哈希的其他属性。此字段可能为空。

GetHashListRequest

用于获取哈希列表的请求，该列表可以是威胁列表，也可以是非威胁列表（例如全局缓存）。

V5 中的新变化：之前在 V4 中称为 states 的内容已重命名为 version，以便更清晰地表达。列表现在已命名，并移除了平台类型和威胁条目类型。现在，多个列表可以具有相同的威胁类型，或者单个列表可以涉及多种威胁类型。与 V4 的可变长度哈希前缀（在许多客户端实现中造成了问题）相比，列表中的所有哈希现在都具有单一长度，从而可以实现更高效的客户端实现。简化了限制，并移除了压缩类型（始终应用压缩）。

字段
name	string 必需。相应特定哈希列表的名称。可以是威胁列表，也可以是全局缓存。
version	bytes 客户端已有的哈希列表的版本。如果客户端是首次提取哈希列表，则此字段必须留空。否则，客户端应提供之前从服务器收到的版本。客户端不得操纵这些字节。 V5 中的新增功能：在 API 的 V4 中，此参数名为 states；现在，为了清晰起见，已将其重命名为 version。
size_constraints	SizeConstraints 列表的大小限制。如果省略，则表示没有限制。建议在处理能力、带宽或存储空间有限的所有设备上使用限制。

HashList

由名称标识的哈希列表。

字段
name	string 哈希列表的名称。请注意，全局缓存也只是一个哈希列表，可在此处进行参考。
version	bytes 哈希列表的版本。客户端不得操纵这些字节。
partial_update	bool 如果为 true，则表示这是包含添加和移除的部分差异，具体取决于客户端已有的内容。如果值为 false，则表示这是完整的哈希列表。 如果为 false，客户端必须删除此哈希列表的所有本地存储版本。这意味着，客户端拥有的版本严重过时，或者客户端数据被认为已损坏。compressed_removals 字段将为空。 如果为 true，客户端必须通过应用移除操作，然后再应用添加操作来应用增量更新。
compressed_removals	RiceDeltaEncoded32Bit 删除索引的 Rice-delta 编码版本。由于每个哈希列表的条目数肯定少于 2^32，因此索引被视为 32 位整数并进行编码。
minimum_wait_duration	Duration 客户端应至少等待这么长时间才能再次获取哈希列表。如果省略或为零，客户端应立即提取，因为这表示服务器有额外的更新要发送给客户端，但由于客户端指定的限制而无法发送。
sha256_checksum	bytes 所有哈希的排序列表，再次使用 SHA256 进行哈希处理。这是应用所提供的更新后，数据库中存在的所有哈希的排序列表的校验和。如果未提供任何更新，服务器将省略此字段，以指示客户端应使用现有校验和。
metadata	HashListMetadata 有关哈希列表的元数据。此字段不会由 GetHashList 方法填充，但会由 ListHashLists 方法填充。
联合字段 compressed_additions。添加内容的 Rice-delta 编码版本。添加项的哈希前缀长度在列表中的所有添加项中都是统一的。compressed_additions 只能是下列其中一项：
additions_four_bytes	RiceDeltaEncoded32Bit 4 字节加法。
additions_eight_bytes	RiceDeltaEncoded64Bit 8 字节加法。
additions_sixteen_bytes	RiceDeltaEncoded128Bit 16 字节的加法。
additions_thirty_two_bytes	RiceDeltaEncoded256Bit 32 字节的添加。

HashListMetadata

有关特定哈希列表的元数据。

字段
threat_types[]	ThreatType 无序列表。如果不为空，则表示哈希列表是一种威胁列表，并枚举与此哈希列表中的哈希或哈希前缀关联的威胁类型。如果条目不代表威胁（即代表可能安全的类型），则可能为空。
likely_safe_types[]	LikelySafeType 无序列表。如果此字段不为空，则表示哈希列表代表的是可能安全的哈希列表，并且此字段会列举这些哈希被视为可能安全的方式。此字段与 threat_types 字段互斥。
description	string 有关此列表的人类可读说明。使用英语撰写。
hash_length	HashLength 相应哈希列表支持的哈希长度。每个哈希列表将仅支持一种长度。如果针对同一组威胁类型或安全类型引入了不同的哈希长度，则会以单独列表的形式引入，并具有不同的名称和相应的哈希长度设置。

HashLength

哈希列表中的哈希长度。

枚举
HASH_LENGTH_UNSPECIFIED	未指定长度。
FOUR_BYTES	每个哈希都是一个四字节前缀。
EIGHT_BYTES	每个哈希都是一个 8 字节的前缀。
SIXTEEN_BYTES	每个哈希都是一个 16 字节的前缀。
THIRTY_TWO_BYTES	每个哈希都是一个 32 字节的完整哈希。

LikelySafeType

可能安全的网站类型。

请注意，SearchHashesResponse 有意不包含 LikelySafeType。

枚举
LIKELY_SAFE_TYPE_UNSPECIFIED	未知。
GENERAL_BROWSING	此网站可能足够安全，可供一般浏览。这也称为全局缓存。
CSD	此网站可能足够安全，无需运行客户端检测模型或密码保护检查。
DOWNLOAD	此网站可能足够安全，因此无需检查来自该网站的下载内容。

ListHashListsRequest

列出可用哈希列表的请求。

字段
page_size	int32 要返回的哈希列表的最大数量。服务返回的值可能小于此值。如果未指定，服务器将选择一个页面大小，该大小可能大于哈希列表的数量，因此无需分页。
page_token	string 从之前的 ListHashLists 调用接收的页面令牌。利用其进行后续页面检索。

ListHashListsResponse

包含有关哈希列表的元数据的响应。

字段
hash_lists[]	HashList 哈希列表以任意顺序列出。只会包含有关哈希列表的元数据，不会包含内容。
next_page_token	string 可作为 page_token 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

RiceDeltaEncoded128Bit

与 RiceDeltaEncoded32Bit 相同，但此函数会对 128 位数字进行编码。

字段
first_value_hi	uint64 编码数据（哈希）中第一个条目的高 64 位。如果该字段为空，则高 64 位全为零。
first_value_lo	fixed64 编码数据（哈希）中第一个条目的低 64 位。如果该字段为空，则低 64 位全部为零。
rice_parameter	int32 Golomb-Rice 参数。此参数保证介于 99 到 126 之间（含）。
entries_count	int32 编码数据中采用差分编码的条目数。如果仅编码了一个整数，则此值为零，并且该单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的编码增量。

RiceDeltaEncoded256Bit

与 RiceDeltaEncoded32Bit 相同，但此函数可对 256 位数字进行编码。

字段
first_value_first_part	uint64 编码数据（哈希）中第一个条目的前 64 位。如果该字段为空，则前 64 位均为零。
first_value_second_part	fixed64 编码数据（哈希）中第一个条目的第 65 位到第 128 位。如果该字段为空，则第 65 位到第 128 位均为零。
first_value_third_part	fixed64 编码数据（哈希）中第一个条目的第 129 位到第 192 位。如果该字段为空，则第 129 位到第 192 位均为零。
first_value_fourth_part	fixed64 编码数据（哈希）中第一个条目的后 64 位。如果该字段为空，则最后 64 位均为零。
rice_parameter	int32 Golomb-Rice 参数。此参数保证介于 227 到 254 之间（含首尾）。
entries_count	int32 编码数据中采用差分编码的条目数。如果仅编码了一个整数，则此值为零，并且该单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的编码增量。

RiceDeltaEncoded32Bit

Rice-Golomb 编码的数据。用于哈希或移除索引。可以保证，此处的每个哈希或索引都具有相同的长度，并且此长度正好为 32 位。

一般来说，如果我们按字典顺序对所有条目进行排序，会发现高阶位往往不如低阶位那样频繁变化。这意味着，如果我们还考虑条目之间的相邻差分，则高阶位的概率很高为零。这种方法利用了零概率较高的特点，即选择一定数量的位；所有比这些位更重要的位都可能为零，因此我们使用一元编码。请参阅 rice_parameter 字段。

历史记录：Rice-delta 编码首次用于此 API 的 V4 版本。在 V5 中，我们做出了两项重大改进：首先，Rice-delta 编码现在可用于长度超过 4 字节的哈希前缀；其次，编码后的数据现在被视为大端字节序，从而避免了代价高昂的排序步骤。

字段
first_value	uint32 编码数据（哈希或索引）中的第一个条目，或者，如果仅编码了一个哈希前缀或索引，则为该条目的值。如果该字段为空，则相应条目的值为零。
rice_parameter	int32 Golomb-Rice 参数。此参数保证介于 3 到 30 之间（含）。
entries_count	int32 编码数据中采用差分编码的条目数。如果仅编码了一个整数，则此值为零，并且该单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的编码增量。

RiceDeltaEncoded64Bit

与 RiceDeltaEncoded32Bit 相同，但此函数可对 64 位数字进行编码。

字段
first_value	uint64 编码数据（哈希）中的第一个条目，或者，如果仅编码了一个哈希前缀，则为该条目的值。如果该字段为空，则相应条目的值为零。
rice_parameter	int32 Golomb-Rice 参数。此参数保证介于 35 到 62 之间（含）。
entries_count	int32 编码数据中采用差分编码的条目数。如果仅编码了一个整数，则此值为零，并且该单个值将存储在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 编码器编码的编码增量。

SearchHashesRequest

客户端发出的用于搜索特定哈希前缀的请求。

此功能旨在仅搜索威胁列表，而不搜索非威胁列表（例如全局缓存）。

V5 中的新功能：客户端无需指定 ClientInfo 或本地数据库中哈希列表的状态。这是为了更好地保护您的隐私。此外，客户端无需发送其感兴趣的威胁类型。

字段
hash_prefixes[]	bytes 必需。要查找的哈希前缀。客户端不得发送超过 1000 个哈希前缀。不过，按照网址处理程序，客户端不应需要发送超过 30 个哈希前缀。 目前，每个哈希前缀的长度都必须正好为 4 个字节。未来可能会放宽此限制。
filter	string 可选。如果客户端需要过滤，例如仅检索特定类型的威胁，则可以指定。如果省略，则返回所有匹配的威胁。强烈建议省略此参数，以便获得“安全浏览”功能提供的最全面的保护。 过滤条件使用 Google 通用表达式语言指定，您可以在 https://github.com/google/cel-spec 中找到该语言以及一般示例。以下是一些可在此处使用的具体示例： 过滤条件 "threat_type == ThreatType.SOCIAL_ENGINEERING" 要求威胁类型 FullHashDetail 必须为 SOCIAL_ENGINEERING。标识符 "threat_type" 指的是当前威胁类型。标识符 "ThreatType" 指的是所有可能的威胁类型的集合。 过滤条件 "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" 要求威胁类型必须为 UNWANTED_SOFTWARE 或 MALWARE。

SearchHashesResponse

搜索威胁哈希后返回的响应。

如果未找到任何内容，服务器将返回“确定”状态（HTTP 状态代码 200），但 full_hashes 字段为空，而不是返回“未找到”状态（HTTP 状态代码 404）。

V5 中的新变化：FullHash 和 FullHashDetail 分开了。如果哈希表示某个网站存在多种威胁（例如，同时存在恶意软件和社会工程），则无需像在 V4 中那样发送两次完整哈希。此外，缓存时长已简化为单个 cache_duration 字段。

字段
full_hashes[]	FullHash 无序列表。找到的完整哈希的无序列表。
cache_duration	Duration 客户端缓存时长。客户端必须将此时长添加到当前时间，以确定过期时间。然后，过期时间会应用于客户端在请求中查询的每个哈希前缀，无论响应中返回了多少个完整哈希。即使服务器未针对特定哈希前缀返回任何完整哈希，客户端也必须缓存此事实。 当且仅当字段 full_hashes 为空时，客户端可以增加 cache_duration 以确定比服务器指定的时间更晚的新过期时间。在任何情况下，增加后的缓存时长都不得超过 24 小时。 重要提示：客户端不得假定服务器会针对所有响应返回相同的缓存时长。服务器可能会根据具体情况为不同的响应选择不同的缓存时长。

SearchUrlsRequest

客户端发出的用于搜索与指定网址匹配的威胁的请求。

此功能旨在仅搜索威胁列表，而不搜索非威胁列表（例如全局缓存）。

字段
urls[]	string 必需。要查找的网址。客户端不得发送超过 50 个网址。

SearchUrlsResponse

搜索与指定网址匹配的威胁后返回的响应。

如果未找到任何内容，服务器将返回“确定”状态（HTTP 状态代码 200），但 threats 字段为空，而不是返回“未找到”状态（HTTP 状态代码 404）。

字段
threats[]	ThreatUrl 无序列表。找到的威胁匹配项的无序列表。每个条目都包含一个网址以及与该网址匹配的威胁类型。列表大小可能大于请求中的网址数量，因为系统会考虑网址的所有表达式。
cache_duration	Duration 客户端缓存时长。客户端必须将此时长添加到当前时间，以确定过期时间。然后，过期时间会应用于客户端在请求中查询的每个网址，无论响应中返回了多少个网址。即使服务器未针对特定网址返回任何匹配项，客户端也必须缓存此事实。 当且仅当字段 threats 为空时，客户端可以增加 cache_duration 以确定比服务器指定的时间更晚的新过期时间。在任何情况下，增加后的缓存时长都不得超过 24 小时。 重要提示：客户端不得假定服务器会针对所有响应返回相同的缓存时长。服务器可能会根据具体情况为不同的响应选择不同的缓存时长。

SizeConstraints

对哈希列表大小的限制。

字段
max_update_entries	int32 条目数量上限。相应更新所含的条目数量不会超过此值，但可能会少于此值。此值必须至少为 1024。如果省略或为零，则不设置更新大小限制。
max_database_entries	int32 设置客户端愿意在列表的本地数据库中存储的条目数量上限。（服务器可能会导致客户端存储的条目数量少于此值。）如果省略或为零，则不设置数据库大小限制。

ThreatAttribute

威胁的属性。这些属性可能会为特定威胁赋予额外的含义，但不会影响威胁类型。例如，一个属性可能指定较低的置信度，而另一个属性可能指定较高的置信度。未来可能会添加更多属性。

枚举
THREAT_ATTRIBUTE_UNSPECIFIED	未知属性。如果服务器返回此值，客户端应完全忽略封装的 FullHashDetail。
CANARY	表示不应将 threat_type 用于强制执行。
FRAME_ONLY	表示 threat_type 仅应用于对框架的强制执行。

ThreatType

威胁类型。

枚举
THREAT_TYPE_UNSPECIFIED	威胁类型未知。如果服务器返回此值，客户端应完全忽略封装的 FullHashDetail。
MALWARE	恶意软件威胁类型。恶意软件是指符合以下特征的所有软件或移动应用：蓄意危害计算机、移动设备、计算机/移动设备上运行的软件或计算机/移动设备用户。恶意软件会表现出各种恶意行为，其中包括：未经用户同意就擅自安装软件，以及安装病毒等有害软件。 点击此处了解详情。
SOCIAL_ENGINEERING	社会工程学威胁类型。社交工程学网页会虚假声称代表第三方行事，目的是让观看者误以为真，从而执行只有在信任该第三方的真实代理人时才会执行的操作。网络钓鱼是一种社会工程学攻击，会诱骗观看者执行提供信息（例如登录凭据）的特定操作。 点击此处了解详情。
UNWANTED_SOFTWARE	垃圾软件威胁类型。垃圾软件是指不符合 Google 的软件准则但不是恶意软件的任何软件。
POTENTIALLY_HARMFUL_APPLICATION	Google Play 保护机制针对 Play 商店使用的潜在有害应用威胁类型。

ThreatUrl

与一种或多种威胁相匹配的网址。

字段
url	string 与一个或多个威胁相匹配的所请求网址。
threat_types[]	ThreatType 无序列表。相应网址被归类为的威胁的无序列表。