Method: threatListUpdates.fetch

擷取威脅清單的最新資訊。客戶可以一次要求更新多份名單。

HTTP 要求

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "client": {
    object (ClientInfo)
  },
  "listUpdateRequests": [
    {
      object (ListUpdateRequest)
    }
  ]
}
欄位
client

object (ClientInfo)

用戶端中繼資料。
listUpdateRequests[]

object (ListUpdateRequest)

要求的威脅清單更新。

回應主體

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

JSON 表示法 
{
  "listUpdateResponses": [
    {
      object (ListUpdateResponse)
    }
  ],
  "minimumWaitDuration": string
}
欄位
listUpdateResponses[]

object (ListUpdateResponse)

用戶端要求的清單更新。這裡的回應數可能會少於用戶端傳送的要求數量。例如當伺服器沒有特定清單的更新時。
minimumWaitDuration

string (Duration format)

用戶端發出任何更新要求前必須等待的最短持續時間。如未設定這個欄位，用戶端可以按需求更新。

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

ListUpdateRequest

單一清單更新要求。

JSON 表示法 
{
  "threatType": enum (ThreatType),
  "platformType": enum (PlatformType),
  "threatEntryType": enum (ThreatEntryType),
  "state": string,
  "constraints": {
    object (Constraints)
  }
}
欄位
threatType

enum (ThreatType)

清單中項目所引致的威脅類型。
platformType

enum (PlatformType)

清單中項目可能面臨風險的平台類型。
threatEntryType

enum (ThreatEntryType)

清單中顯示的項目類型。
state

string (bytes format)

要求清單的用戶端目前的狀態 (自上次成功更新清單後收到的加密用戶端狀態)。

Base64 編碼的字串。
constraints

object (Constraints)

與這項要求相關的限制條件。

限制

本次更新的限制。

JSON 表示法 
{
  "maxUpdateEntries": integer,
  "maxDatabaseEntries": integer,
  "region": string,
  "supportedCompressions": [
    enum (CompressionType)
  ],
  "language": string,
  "deviceLocation": string
}
欄位
maxUpdateEntries

integer

項目數上限。更新的內容將包含超過這個值的項目。其次是 2 的 2**10 到 2**20 度。如為 0，則未設定更新大小上限。
maxDatabaseEntries

integer

設定用戶端在指定清單的本機資料庫中，願意擁有的項目數量上限。其次是 2 的 2**10 到 2**20 度。如為零，則未設定資料庫大小限制。
region

string

要求取得特定地理位置的清單。如未設定，伺服器可能會根據使用者的 IP 位址挑選這個值。須使用 ISO 3166-1 alpha-2 格式。
supportedCompressions[]

enum (CompressionType)

用戶端支援的壓縮類型。
language

string

要求特定語言的清單。須採用 ISO 639 alpha-2 格式。
deviceLocation

string

客戶的實際位置，以 ISO 31166-1 alpha-2 區碼表示。

CompressionType

威脅項目集的壓縮方式。

列舉
COMPRESSION_TYPE_UNSPECIFIED 不明。
RAW 未經壓縮的原始資料。
RICE Rice-Golomb 編碼資料。

ListUpdateResponse

對個別清單進行更新。

JSON 表示法 
{
  "threatType": enum (ThreatType),
  "threatEntryType": enum (ThreatEntryType),
  "platformType": enum (PlatformType),
  "responseType": enum (ResponseType),
  "additions": [
    {
      object (ThreatEntrySet)
    }
  ],
  "removals": [
    {
      object (ThreatEntrySet)
    }
  ],
  "newClientState": string,
  "checksum": {
    object (Checksum)
  }
}
欄位
threatType

enum (ThreatType)

系統會傳回所傳回資料的威脅類型。
threatEntryType

enum (ThreatEntryType)

威脅的格式。
platformType

enum (PlatformType)

傳回資料的平台類型。
responseType

enum (ResponseType)

回應類型。這可能表示用戶端在收到回應時需要執行動作。
additions[]

object (ThreatEntrySet)

要新增至本機威脅類型清單的一組項目。重複以上，允許透過單一回應傳送壓縮與原始資料的組合。
removals[]

object (ThreatEntrySet)

要從本機威脅類型清單中移除的一組項目。實務上，這個欄位空白或只包含一個 ThreatEntrySet。
newClientState

string (bytes format)

新的用戶端狀態 (加密格式)。客戶無法理解。

Base64 編碼的字串。
checksum

object (Checksum)

套用提供的更新後，預期用戶端狀態的 SHA256 雜湊；也就是套用提供的更新後，資料庫中呈現的所有雜湊清單。如果用戶端狀態與預期狀態不符，用戶端必須忽略這項更新，並於稍後重試。

ResponseType

傳送至用戶端的回應類型。

列舉
RESPONSE_TYPE_UNSPECIFIED 不明。
PARTIAL_UPDATE 部分更新會套用至用戶端的現有本機資料庫。
FULL_UPDATE 完整更新會取代用戶端的完整本機資料庫，這可能表示客戶十分過時，或被誤以為已損毀。

ThreatEntrySet

應在用戶端的本機資料庫中新增或移除的一組威脅。

JSON 表示法 
{
  "compressionType": enum (CompressionType),
  "rawHashes": {
    object (RawHashes)
  },
  "rawIndices": {
    object (RawIndices)
  },
  "riceHashes": {
    object (RiceDeltaEncoding)
  },
  "riceIndices": {
    object (RiceDeltaEncoding)
  }
}
欄位
compressionType

enum (CompressionType)

此組合中項目的壓縮類型。
rawHashes

object (RawHashes)

採用 SHA256 格式的原始項目。
rawIndices

object (RawIndices)

本機清單的原始移除索引。
riceHashes

object (RiceDeltaEncoding)

經過編碼的 4 位元組前置字串，屬於 SHA256 格式項目，使用 Golomb-Rice 編碼。雜湊會轉換為 uint32，並依遞增順序排序，接著以 delta 編碼，並以編碼後儲存的資料儲存。
riceIndices

object (RiceDeltaEncoding)

使用 Golomb-Rice 編碼的本機編碼依字母順序排序的清單索引。用於傳送壓縮移除索引。移除索引 (uint32) 會依遞增順序排序，然後採用 delta 編碼，並以編碼形式儲存。

RawHashes

未壓縮的威脅項目，採用特定前置字串長度的雜湊格式。雜湊大小可以介於 4 到 32 個位元組之間。大部分網址多半是 4 個位元組，但部分雜湊會與熱門網址的雜湊衝突，因而延長。

用於將 ThreatEntrySet 傳送給不支援壓縮的用戶端，或是將非 4 位元組雜湊傳送給支援壓縮功能的用戶端。

JSON 表示法 
{
  "prefixSize": integer,
  "rawHashes": string
}
欄位
prefixSize

integer

經過編碼的每個前置字串的位元組數。這個欄位可以指向介於 4 (最短前置字元) 到 32 (完整 SHA256 雜湊) 之間的任何位置。
rawHashes

string (bytes format)

採用二進位格式的雜湊，串連為一個長字串。雜湊會依字母順序排序。如果是 JSON API 使用者，雜湊為 Base64 編碼。

Base64 編碼的字串。

RawIndices

要從本機清單移除的一組原始索引。

JSON 表示法 
{
  "indices": [
    integer
  ]
}
欄位
indices[]

integer

要從按字母順序排序的當地清單中移除的索引。

RiceDeltaEncoding

Rice-Golomb 編碼資料。用於傳送經過壓縮的 4 位元組雜湊或壓縮移除索引。

JSON 表示法 
{
  "firstValue": string,
  "riceParameter": integer,
  "numEntries": integer,
  "encodedData": string
}
欄位
firstValue

string (int64 format)

編碼資料中第一個項目的偏移值，或是如果只編碼單一整數，該單一整數的值。如果這個欄位空白或遺漏，請假設 0。
riceParameter

integer

Golomb-Rice 參數，也就是介於 2 到 28 之間的數字。如果 numEntries 為零，則缺少這個欄位 (亦即零)。
numEntries

integer

編碼資料中採用差異遷移的項目數量。如果只對一個整數編碼，此值將為零，且單一值會儲存在 firstValue 中。
encodedData

string (bytes format)

使用 Golomb-Rice 編碼器編碼的編碼差異。

Base64 編碼的字串。

檢查碼

用戶端本機資料庫的預期狀態。

JSON 表示法 
{
  "sha256": string
}
欄位
sha256

string (bytes format)

用戶端狀態的 SHA256 雜湊，也就是資料庫中所有雜湊的排序清單。

Base64 編碼的字串。