- 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 的 2**10 到 2**20 度。如為 0,則未設定更新大小上限。 |
maxDatabaseEntries |
設定用戶端在指定清單的本機資料庫中,願意擁有的項目數量上限。其次是 2 的 2**10 到 2**20 度。如為零,則未設定資料庫大小限制。 |
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 編碼,並以編碼後儲存的資料儲存。 |
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 |
編碼資料中採用差異遷移的項目數量。如果只對一個整數編碼,此值將為零,且單一值會儲存在 |
encodedData |
使用 Golomb-Rice 編碼器編碼的編碼差異。 Base64 編碼的字串。 |
檢查碼
用戶端本機資料庫的預期狀態。
JSON 表示法 | |
---|---|
{ "sha256": string } |
欄位 | |
---|---|
sha256 |
用戶端狀態的 SHA256 雜湊,也就是資料庫中所有雜湊的排序清單。 Base64 編碼的字串。 |