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 之間的 2 次方。如果值為 0，表示未設定更新大小限制。
maxDatabaseEntries

integer

針對指定清單，設定用戶端願意在本機資料庫中的項目數量上限。這應該是 2**10 到 2**20 之間的 2 次方。如果值為 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)

採用 Golomb-Rice 編碼的 SHA256 格式項目的 4 位元組前置字串。系統會將雜湊值轉換成 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 為 0，則缺少這個欄位 (亦即 0)。
numEntries

integer

編碼資料中經過差異編碼的項目數量。如果只編碼一個整數，該值將會是 0，而單一值將儲存在 firstValue 中。
encodedData

string (bytes format)

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

Base64 編碼字串。

檢查碼

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

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

string (bytes format)

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

Base64 編碼字串。