Method: hashes.search

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

这是 https://google.aip.dev/136 定义的自定义方法(自定义方法是指此方法在 Google 的常规 API 开发命名法中具有自定义名称,不是指使用自定义 HTTP 方法)。

HTTP 请求

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

网址采用 gRPC 转码语法。

查询参数

参数
hashPrefixes[]

string (bytes format)

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

目前,每个哈希前缀的长度必须正好为 4 个字节。未来可能会放宽限制。

使用 base64 编码的字符串。

请求正文

请求正文必须为空。

响应正文

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

如果找不到任何结果,服务器将返回 OK 状态(HTTP 状态代码 200)并将 fullHashes 字段留空,而不是返回 NOT_FOUND 状态(HTTP 状态代码 404)。

V5 的新变化FullHashFullHashDetail 分开了。如果一个哈希值表示一个网站存在多个威胁(例如,MALWARE 和 SOCIAL_ENGINEERING),则无需像 V4 那样发送两次完整哈希值。此外,缓存时长已简化为单个 cacheDuration 字段。

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

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

object (FullHash)

无序列表。找到的完整哈希列表(无序列表)。

cacheDuration

string (Duration format)

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

当且仅当字段 fullHashes 为空时,客户端才能增加 cacheDuration 以确定新的到期时间,晚于服务器指定的到期时间。在任何情况下,增加的缓存时长都不得超过 24 小时。

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

该时长以秒为单位,最多包含九个小数位,以“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 消息。因此,客户端应检查所有 ThreatTypeThreatAttribute 枚举值的有效性;如果有任何值被视为无效,客户端必须忽略整个 FullHashDetail 消息。

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

enum (ThreatType)

威胁的类型。此字段不得为空。

attributes[]

enum (ThreatAttribute)

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

ThreatType

威胁类型。

枚举
THREAT_TYPE_UNSPECIFIED 未知威胁类型。如果服务器返回了此属性,客户端应完全忽略封装的 FullHashDetail
MALWARE

恶意软件威胁类型。恶意软件是指符合以下特征的所有软件或移动应用:蓄意危害计算机、移动设备、计算机/移动设备上运行的软件或计算机/移动设备用户。恶意软件会表现出各种恶意行为,其中包括:未经用户同意就擅自安装软件,以及安装病毒等有害软件。

如需了解详情,请参阅此处

SOCIAL_ENGINEERING

社会工程学威胁类型。社交工程网页谎称会代表第三方行事,意图诱使观看者执行某些操作,使观看者仅信任第三方的真正代理。钓鱼式攻击是一种社会工程学攻击,会诱使观看者执行特定操作来提供信息(例如登录凭据)。

如需了解详情,请参阅此处

UNWANTED_SOFTWARE 垃圾软件威胁类型。垃圾软件是指任何不符合 Google 软件准则的软件,但并非恶意软件。
POTENTIALLY_HARMFUL_APPLICATION Google Play 保护机制为 Play 商店使用的可能有害的应用威胁类型。

ThreatAttribute

威胁的属性。这些属性可能为特定威胁提供额外的含义,但不会影响威胁类型。例如,某个属性可以指定较低的置信度,而其他属性可以指定较高的置信度。未来可能会添加更多属性。

枚举
THREAT_ATTRIBUTE_UNSPECIFIED 未知属性。如果服务器返回了此属性,客户端应完全忽略封装的 FullHashDetail
CANARY 表示 ThreatType 不应用于强制执行。
FRAME_ONLY 表示威胁类型应仅用于对帧强制执行。