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**10 和 2**20 之間。如果值為「0」，系統就不會設定更新大小限制。
maxDatabaseEntries

integer

針對指定清單，設定用戶端願意在本機資料庫中保留的項目數量上限。這個值應介於 2**10 和 2**20 之間。如果值為「0」，系統就不會設定資料庫的大小限制。
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 編碼並儲存為 encodedData。
riceIndices

object (RiceDeltaEncoding)

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

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 編碼的字串。