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 的新功能：FullHash 和 FullHashDetail 之間有分隔符。如果雜湊代表網站有多個威脅 (例如同時有惡意軟體和社會工程攻擊)，就不需要像 V4 一樣傳送完整雜湊兩次。此外，快取時間長度已簡化為單一 cacheDuration 欄位。

如果成功，回應主體會含有以下結構的資料：

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

object (FullHash)

未排序的清單。找到的完整雜湊值無序清單。
cacheDuration

string (Duration format)

用戶端快取時間長度。用戶端必須將這個時間長度加到目前時間，才能判斷到期時間。無論回應中傳回多少完整雜湊，這項作業期限都會套用至用戶端在要求中查詢的每個雜湊前置字串。即使伺服器未針對特定雜湊前置字串傳回完整雜湊，用戶端仍必須將此事實快取。

只有在 fullHashes 欄位為空白時，用戶端才會增加 cacheDuration，以便判斷新的到期時間，該時間晚於伺服器指定的時間。無論如何，增加的快取時間不得超過 24 小時。

重要事項：用戶端不得假設伺服器會為所有回應傳回相同的快取時間長度。視情況而定，伺服器可能會為不同的回應選擇不同的快取時間長度。

以秒為單位的時間長度，最多可有 9 個小數位數，結尾為「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 應僅用於在影格上強制執行。