- 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 之間的 2 次方。如果值為 0,表示未設定更新大小限制。 |
maxDatabaseEntries |
針對指定清單,設定用戶端願意在本機資料庫中的項目數量上限。這應該是 2**10 到 2**20 之間的 2 次方。如果值為 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 |
採用 Golomb-Rice 編碼的 SHA256 格式項目的 4 位元組前置字串。系統會將雜湊值轉換成 uint32,先以遞增順序排序,然後對 Delta 編碼並以編碼資料格式儲存。 |
riceIndices |
經過編碼的本機清單索引 (按字母順序排列),並使用 Golomb-Rice 編碼。用於傳送經過壓縮的移除索引。移除索引 (uint32) 會按照遞增順序排序,然後是 Delta 編碼和儲存為編碼資料的資料。 |
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 |
編碼資料中經過差異編碼的項目數量。如果只編碼一個整數,該值將會是 0,而單一值將儲存在 |
encodedData |
使用 Golomb-Rice 編碼器編碼的編碼差異值。 Base64 編碼字串。 |
檢查碼
用戶端本機資料庫的預期狀態。
JSON 表示法 |
---|
{ "sha256": string } |
欄位 | |
---|---|
sha256 |
用戶端狀態的 SHA256 雜湊;也就是資料庫中所有雜湊的排序清單。 Base64 編碼字串。 |