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 不會公開 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)

未排序的清單。與完整雜湊相關的其他屬性。可能沒有內容。

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 表示 ThreatType 只應用於影格強制執行。