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 有所區隔。如果雜湊值代表某個網站有多個威脅 (例如惡意軟體和 SOCIAL_ENGINEERING)，則完整的雜湊值在 V4 中不需要傳送兩倍。此外，快取持續時間已簡化為單一 cacheDuration 欄位。

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

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

object (FullHash)

未排序的清單。找到的完整雜湊清單 (未排序)。
cacheDuration

string (Duration format)

用戶端快取持續時間。用戶端「必須」將這段時間長度新增至目前時間，才能決定到期時間。接著，無論回應中傳回多少完整雜湊，到期時間都會套用至用戶端在要求中查詢的每個雜湊前置字串。即使伺服器未傳回特定雜湊前置字元的完整雜湊，用戶端也「必須」快取這一點。

重要事項：用戶端「不得」假設伺服器針對所有回應傳回相同的快取時間長度。伺服器可以視情況為不同的回應選擇不同的快取持續時間。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。

FullHash

識別出一或多個相符項目的完整雜湊。

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

string (bytes format)

相符的完整雜湊。這是 SHA256 雜湊。長度為 32 個位元組。

Base64 編碼的字串。
fullHashDetails[]

object (FullHashDetail)

未排序的清單。重複欄位，用於識別與這個完整雜湊相關的詳細資料。

FullHashDetail

比對完整雜湊的詳細資料。

前瞻相容性的重要須知：伺服器隨時可能加入新的威脅類型和威脅屬性；這些新增項目被視為小版本變更。根據 Google 的政策規定，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 表示威脅類型不應用於強制執行。
FRAME_ONLY 表示 ThreatType 只應用於強制執行頁框。