- HTTP 要求
- 要求主體
- 回應主體
- ListUpdateRequest
- 限制
- CompressionType
- ListUpdateResponse
- ResponseType
- ThreatEntrySet
- RawHashes
- RawIndices
- RiceDeltaEncoding
- 總和檢查碼
擷取威脅清單的最新更新。客戶可以一次要求更新多份名單。
HTTP 要求
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "client": { object ( |
欄位 | |
---|---|
client |
用戶端中繼資料。 |
listUpdateRequests[] |
要求的威脅清單更新。 |
回應主體
如果成功,回應主體即會包含具有以下結構的資料:
JSON 表示法 |
---|
{
"listUpdateResponses": [
{
object ( |
欄位 | |
---|---|
listUpdateResponses[] |
用戶端要求更新的清單。這裡的回應數量可能少於用戶端傳送的要求數量。舉例來說,如果伺服器沒有特定清單的更新,就可能發生這種情況。 |
minimumWaitDuration |
用戶端發出更新要求前,必須等待的最短持續時間。如果未設定這個欄位,用戶端可能會在需要時盡快更新。 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
ListUpdateRequest
單一清單更新要求。
JSON 表示法 |
---|
{ "threatType": enum ( |
欄位 | |
---|---|
threatType |
清單中項目所構成的威脅類型。 |
platformType |
清單中所列項目有風險的平台類型。 |
threatEntryType |
清單中的項目類型。 |
state |
所要求清單的用戶端目前狀態 (上次成功更新清單時收到的加密用戶端狀態)。 Base64 編碼的字串。 |
constraints |
與這項要求相關聯的限制條件。 |
限制
這項更新的限制條件。
JSON 表示法 |
---|
{
"maxUpdateEntries": integer,
"maxDatabaseEntries": integer,
"region": string,
"supportedCompressions": [
enum ( |
欄位 | |
---|---|
maxUpdateEntries |
項目數的大小上限。更新項目所含的項目不會超過這個值。這個值應介於 2**10 和 2**20 之間。如果值為「0」,系統就不會設定更新大小限制。 |
maxDatabaseEntries |
針對指定清單,設定用戶端願意在本機資料庫中保留的項目數量上限。這個值應介於 2**10 和 2**20 之間。如果值為「0」,系統就不會設定資料庫的大小限制。 |
region |
要求列出特定地理位置的清單。如果未設定,伺服器可能會根據使用者的 IP 位址挑選該值。請採用 ISO 3166-1 alpha-2 格式。 |
supportedCompressions[] |
用戶端支援的壓縮類型。 |
language |
要求特定語言的清單。請採用 ISO 639 alpha-2 格式。 |
deviceLocation |
用戶端的實際位置,以 ISO 31166-1 alpha-2 區碼表示。 |
CompressionType
壓縮威脅項目集的方式。
列舉 | |
---|---|
COMPRESSION_TYPE_UNSPECIFIED |
不明。 |
RAW |
原始未壓縮資料。 |
RICE |
Rice-Golomb 編碼的資料。 |
ListUpdateResponse
更新個別清單。
JSON 表示法 |
---|
{ "threatType": enum ( |
欄位 | |
---|---|
threatType |
傳回資料的威脅類型。 |
threatEntryType |
威脅的格式。 |
platformType |
傳回資料的平台類型。 |
responseType |
回應類型。這可能表示用戶端在收到回應時必須採取行動。 |
additions[] |
要新增至本機威脅類型清單的一組項目。重複項目,可在單一回應中傳送經過壓縮和原始資料的組合。 |
removals[] |
要從本機威脅類型清單中移除的一組項目。在實際操作時,這個欄位會是空白的,或僅含一個 ThreatEntrySet。 |
newClientState |
新的用戶端狀態,採用加密格式。對客戶而言不透明。 Base64 編碼的字串。 |
checksum |
用戶端狀態預期的 SHA256 雜湊;也就是套用提供的更新後,資料庫中所有雜湊的排序清單。如果用戶端狀態與預期狀態不符,用戶端必須忽略此更新並稍後再重試。 |
ResponseType
傳送給用戶端的回應類型。
列舉 | |
---|---|
RESPONSE_TYPE_UNSPECIFIED |
不明。 |
PARTIAL_UPDATE |
部分更新會套用至用戶端現有的本機資料庫, |
FULL_UPDATE |
完整更新會取代用戶端的整個本機資料庫。這意味著用戶端嚴重過時,或客戶被認定為毀損。 |
ThreatEntrySet
應從用戶端的本機資料庫中新增或移除的一組威脅。
JSON 表示法 |
---|
{ "compressionType": enum ( |
欄位 | |
---|---|
compressionType |
這個集合中項目的壓縮類型。 |
rawHashes |
原始 SHA256 格式項目。 |
rawIndices |
本機清單的原始移除索引。 |
riceHashes |
經過編碼的 4 位元組前置字串,格式為 SHA256 格式的項目 (使用 Golomb-Rice 編碼)。雜湊會轉換為 uint32,依遞增順序排序,然後 delta 編碼並儲存為 encodedData。 |
riceIndices |
經過編碼的本地依字母順序排序的清單索引,採用 Golomb-Rice 編碼。用於傳送壓縮的移除索引。移除索引 (uint32) 會依遞增順序排序,然後 delta 編碼並儲存為 encodedData。 |
RawHashes
以特定前置字串長度雜湊格式呈現的未壓縮威脅項目。雜湊大小介於 4 到 32 個位元組之間。多數情況下為 4 個位元組,但如果某些雜湊與熱門網址的雜湊值衝突,系統就會增加雜湊值。
用於將 ThreatEntrySet 傳送至不支援壓縮的用戶端,或傳送非 4 位元組雜湊給支援壓縮的用戶端。
JSON 表示法 |
---|
{ "prefixSize": integer, "rawHashes": string } |
欄位 | |
---|---|
prefixSize |
下列編碼每個前置字元的位元組數。這個欄位可以是 4 (最短前置字元) 到 32 (完整 SHA256 雜湊) 之間的任何位置。 |
rawHashes |
二進位格式的雜湊,串連為一個長字串。雜湊會依字母順序排序。如果是 JSON API 使用者,雜湊會採用 Base64 編碼。 Base64 編碼的字串。 |
RawIndices
要從本機清單中移除的一組原始索引。
JSON 表示法 |
---|
{ "indices": [ integer ] } |
欄位 | |
---|---|
indices[] |
要從依字母順序排序的本機清單中移除的索引。 |
RiceDeltaEncoding
Rice-Golomb 編碼的資料。用於傳送壓縮的 4 位元組雜湊或壓縮後移除索引。
JSON 表示法 |
---|
{ "firstValue": string, "riceParameter": integer, "numEntries": integer, "encodedData": string } |
欄位 | |
---|---|
firstValue |
編碼資料中第一個項目的偏移,如果只編碼一個整數,就是該單一整數的值。如果欄位空白或漏填,請假設為 0。 |
riceParameter |
Golomb-Rice 參數,是介於 2 與 28 之間的數字。如果 |
numEntries |
已編碼資料中經過差異處理的項目數量。如果只編碼了一個整數,這個值將會是零,而單一值也會儲存在 |
encodedData |
使用 Golomb-Rice 編碼器進行編碼的編碼差異。 Base64 編碼的字串。 |
檢查碼
用戶端本機資料庫的預期狀態。
JSON 表示法 |
---|
{ "sha256": string } |
欄位 | |
---|---|
sha256 |
用戶端狀態的 SHA256 雜湊,也就是資料庫中所有雜湊的排序清單。 Base64 編碼的字串。 |