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

選用設定。如果客戶想要篩選功能 (例如只擷取特定種類的威脅)，可指定這項設定。如果省略，系統會傳回所有相符的威脅。為了獲得最完整的安全瀏覽功能，我們強烈建議您略過這個設定。

此篩選器是使用 Google 一般運算語言指定，如需瞭解一般範例，請造訪 https://github.com/google/cel-spec。以下列舉幾個適用的例子：

「"threatType == ThreatType.SOCIAL_ENGINEERING"」篩選器要求 FullHashDetail 中的威脅類型必須是 SOCIAL_ENGINEERING。ID "threatType" 是指目前的威脅類型。ID "ThreatType" 是指所有可能的威脅類型集合。

篩選器 "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" 要求威脅類型必須是 UNWANTED_SOFTWARE 或 MALWARE。

要求主體

要求主體必須為空白。

回應主體

搜尋威脅雜湊後傳回的回應。

如果找不到任何內容，伺服器會傳回「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)

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

ThreatAttribute

威脅的種類。這些屬性對特定威脅有額外的意義，但不會影響威脅類型。舉例來說，某個屬性指定的可信度可能會較低，而另一個屬性則能指定較高的可信度。日後可能會新增更多屬性。

列舉
THREAT_ATTRIBUTE_UNSPECIFIED 未知的屬性。如果伺服器傳回此方法，用戶端應完全忽略內含的 FullHashDetail。
CANARY 表示 ThreatType 不應用於強制執行。
FRAME_ONLY 表示 ThreatType 只應用於影格強制執行。