Method: hashes.search

搜索与指定前缀匹配的完整哈希。

这是 https://google.aip.dev/136 定义的自定义方法（该自定义方法是指此方法具有采用 Google 通用 API 开发命名法的自定义名称，不是指使用自定义 HTTP 方法）。

HTTP 请求

GET https://safebrowsing.googleapis.com/v5alpha1/hashes:search

网址采用 gRPC 转码语法。

查询参数

参数
hashPrefixes[]

string (bytes format)

必需。要查找的哈希前缀。客户端发送的哈希前缀不得超过 1000 个。不过，按照网址处理流程，客户端不需要发送超过 30 个哈希前缀。

目前，每个哈希前缀的长度必须正好为 4 个字节。将来可以放宽这一要求。

使用 base64 编码的字符串。
filter

string

可选。如果客户端要过滤，例如仅检索特定类型的威胁，可指定此字段。如果省略，则返回所有匹配的威胁。我们强烈建议您省略此设置，以便充分利用安全浏览功能，从而提供最全面的保护。如需了解过滤器表达式语法，请参阅 https://google.aip.dev/160。

请求正文

请求正文必须为空。

响应正文

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

如果找不到任何错误消息，服务器将返回“OK”状态（HTTP 状态代码 200），并将 fullHashes 字段留空，而不是返回 NOT_FOUND 状态（HTTP 状态代码 404）。

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

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

JSON 表示法 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
字段
fullHashes[]

object (FullHash)

无序列表。找到的完整哈希值的无序列表。
cacheDuration

string (Duration format)

客户端缓存时长。客户端必须将此时长添加到当前时间，以确定到期时间。然后，到期时间将应用于客户端在请求中查询的每个哈希前缀，无论响应中返回了多少完整的哈希。即使服务器没有针对特定的哈希前缀返回完整的哈希，客户端也必须缓存这一事实。

重要提示：客户端不得假定服务器对所有响应返回相同的缓存时长。服务器可以根据具体情况为不同的响应选择不同的缓存时长。

此时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

FullHash

用一个或多个匹配项标识的完整哈希。

JSON 表示法 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
字段
fullHash

string (bytes format)

匹配的完整哈希。这是 SHA256 哈希值。长度正好为 32 个字节。

使用 base64 编码的字符串。
fullHashDetails[]

object (FullHashDetail)

无序列表。一个重复字段，用于标识与此完整哈希相关的详细信息。

FullHashDetail

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

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

JSON 表示法 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
字段
threatType

enum (ThreatType)

威胁的类型。此字段一律不为空。
attributes[]

enum (ThreatAttribute)

无序列表。关于这些完整哈希的其他属性。此字段可能为空。

ThreatAttribute

威胁的属性。这些属性可能对特定威胁赋予其他含义，但不会影响威胁类型。例如，某个属性指定的置信度可能较低，而其他属性指定的置信度可能较高。未来我们可能会添加更多属性。

枚举
THREAT_ATTRIBUTE_UNSPECIFIED 未知属性。如果服务器返回此错误代码，则客户端应完全忽略外围的 FullHashDetail。
CANARY 表示不应将 threatType 用于强制执行。
FRAME_ONLY 表示 threatType 应仅用于对帧强制执行。