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 分開。如果雜湊代表網站有多項威脅 (例如 MALWARE 和 SOCIAL_ENGINEERING)，則不需要像 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 僅適用於對影格強制執行。