索引
SafeBrowsing(介面)Checksum(訊息)ClientInfo(訊息)CompressionType(列舉)FetchThreatListUpdatesRequest(訊息)FetchThreatListUpdatesRequest.ListUpdateRequest(訊息)FetchThreatListUpdatesRequest.ListUpdateRequest.Constraints(訊息)FetchThreatListUpdatesResponse(訊息)FetchThreatListUpdatesResponse.ListUpdateResponse(訊息)FetchThreatListUpdatesResponse.ListUpdateResponse.ResponseType(列舉)FindFullHashesRequest(訊息)FindFullHashesResponse(訊息)FindThreatMatchesRequest(訊息)FindThreatMatchesResponse(訊息)ListThreatListsResponse(訊息)PlatformType(列舉)RawHashes(訊息)RawIndices(訊息)RiceDeltaEncoding(訊息)ThreatEntry(訊息)ThreatEntryMetadata(訊息)ThreatEntryMetadata.MetadataEntry(訊息)ThreatEntrySet(訊息)ThreatEntryType(列舉)ThreatInfo(訊息)ThreatListDescriptor(訊息)ThreatMatch(訊息)ThreatType(列舉)
安全瀏覽
安全瀏覽 API 可讓用戶端檢查網頁資源 (最常見的是網址)，將其與 Google 持續更新的不安全網頁資源清單比對。Safe Browsing API (v4) 提供 Update API 和 Lookup API。
Update API 專為大型客戶設計，其中包含 FindFullHashes 和 FetchThreatListUpdates 方法。Update API 要求用戶端在本機資料庫中維護已下載的威脅清單。
首先，用戶端會比對本機清單，判斷特定網路資源的狀態 (安全或不安全)。通常，清單會包含黑名單網址運算式的雜湊前置字串。如要檢查網址，用戶端會產生指定網址的雜湊，並檢查本機清單中的前置字串是否有衝突；如果找到相符的前置字串，用戶端會透過 FindFullHashes 方法取得與相符雜湊前置字串相關聯的完整雜湊。接著，用戶端會將本機完整雜湊與傳回的完整雜湊進行比對；如果相符，表示網址不安全。
其次，用戶端會透過 FetchThreatListUpdates 方法取得本機資料庫的更新內容，該方法會採用用戶端的目前狀態，並傳回更新的用戶端狀態，以及用戶端應套用至本機威脅清單的變更。
Lookup API 專為較小的用戶端設計，可讓用戶端透過 FindThreatMatches 方法，直接將資源與 Safe Browsing 威脅清單進行比對。
使用 Update API 或 Lookup API 的用戶端可以透過 ListThreatLists 方法取得可供下載的 Safe Browsing 威脅清單。
{-- TRUSTED_THREAT_REPORTER：可信任的威脅用戶端可以透過 SubmitThreatReport 方法，將報告提交給 Google 進行分析。--}
| FetchThreatListUpdates |
|---|
|
擷取最新的威脅清單更新內容。用戶端可以一次要求多個清單的更新。 |
| FindFullHashes |
|---|
|
找出與要求的雜湊前置字串相符的完整雜湊。 |
| FindThreatMatches |
|---|
|
找出與安全瀏覽清單相符的威脅項目。 |
| ListThreatLists |
|---|
|
列出可供下載的安全瀏覽威脅清單。 |
檢查碼
用戶端本機資料庫的預期狀態。
| 欄位 | |
|---|---|
sha256 |
用戶端狀態的 SHA256 雜湊，也就是資料庫中所有雜湊的排序清單。 |
ClientInfo
與 Safe Browsing API 要求相關聯的用戶端中繼資料。
| 欄位 | |
|---|---|
client_id |
用戶端 ID，可 (希望) 明確識別 Safe Browsing API 的用戶端實作項目。 |
client_version |
用戶端實作版本。 |
CompressionType
威脅項目集可壓縮的方式。
| 列舉 | |
|---|---|
COMPRESSION_TYPE_UNSPECIFIED |
未知。 |
RAW |
原始未壓縮資料。 |
RICE |
Rice-Golomb 編碼資料。 |
FetchThreatListUpdatesRequest
說明 Safe Browsing API 更新要求。用戶端可以在單一要求中要求更新多個清單。如果伺服器沒有該清單的更新內容，可能就不會回應所有要求。注意：欄位索引 2 未使用。NEXT: 5
| 欄位 | |
|---|---|
client |
用戶端中繼資料。 |
list_update_requests[] |
要求的威脅清單更新項目。 |
ListUpdateRequest
單一清單更新要求。
| 欄位 | |
|---|---|
threat_type |
清單中項目所造成的威脅類型。 |
platform_type |
清單中項目所代表的平台類型。 |
threat_entry_type |
清單中的項目類型。 |
state |
要求清單的目前用戶端狀態 (從上次成功的清單更新收到的加密用戶端狀態)。 |
constraints |
與此要求相關的限制。 |
限制
本次更新的限制條件。
| 欄位 | |
|---|---|
max_update_entries |
項目數量上限。更新內容不會超過這個值。這個值應為 2**10 和 2**20 之間的 2 次方。如果為零，則不會設定更新大小限制。 |
max_database_entries |
設定用戶端願意在指定清單的本機資料庫中保留的項目數量上限。這個值應為 2**10 和 2**20 之間的 2 次方。如果為零，則不會設定資料庫大小限制。 |
region |
要求特定地理位置的清單。如果未設定，伺服器可能會根據使用者的 IP 位址選擇該值。應採用 ISO 3166-1 alpha-2 格式。 |
supported_compressions[] |
用戶端支援的壓縮類型。 |
language |
要求取得特定語言的清單。預期格式為 ISO 639 alpha-2。 |
device_location |
用戶端的實際位置，以 ISO 31166-1 alpha-2 區碼表示。 |
FetchThreatListUpdatesResponse
| 欄位 | |
|---|---|
list_update_responses[] |
客戶要求的清單更新。這裡的回應數量可能會少於用戶端傳送的要求數量。舉例來說，如果伺服器沒有特定清單的更新內容，就會發生這種情況。 |
minimum_wait_duration |
用戶端必須等待的最短時間，才能發出任何更新要求。如果未設定這個欄位，客戶可以隨時更新。 |
ListUpdateResponse
個別清單的更新。
| 欄位 | |
|---|---|
threat_type |
傳回資料的威脅類型。 |
threat_entry_type |
威脅的格式。 |
platform_type |
傳回資料的平台類型。 |
response_type |
回應類型。這可能表示用戶端在收到回應時需要採取行動。 |
additions[] |
一組要新增至本地威脅類型清單的項目。重複使用，讓壓縮和原始資料可在單一回應中傳送。 |
removals[] |
從本機威脅類型清單中移除的項目組合。實際上，這個欄位會是空白，或只包含一個 ThreatEntrySet。 |
new_client_state |
新的用戶端狀態，以加密格式呈現。對用戶端而言是不可見的。 |
checksum |
用戶端狀態的預期 SHA256 雜湊值，也就是在套用提供的更新後，資料庫中所有雜湊值的排序清單。如果用戶端狀態與預期狀態不符，用戶端必須忽略這項更新，並稍後再試一次。 |
ResponseType
傳送至用戶端的回應類型。
| 列舉 | |
|---|---|
RESPONSE_TYPE_UNSPECIFIED |
未知。 |
PARTIAL_UPDATE |
部分更新會套用至用戶端現有的本機資料庫。 |
FULL_UPDATE |
完整更新會取代用戶端的整個本機資料庫。這表示用戶端嚴重過時，或是用戶端疑似已損毀。 |
FindFullHashesRequest
要求傳回與提供的雜湊前置字元相符的完整雜湊。
| 欄位 | |
|---|---|
client |
用戶端中繼資料。 |
client_states[] |
每個用戶端的本機威脅清單目前的用戶端狀態。 |
threat_info |
要檢查的清單和雜湊。 |
api_client |
與用戶端實作項目上建構的較高層級 API 呼叫端相關的用戶端中繼資料。 |
FindFullHashesResponse
| 欄位 | |
|---|---|
matches[] |
與要求的前置字元相符的完整雜湊。 |
minimum_wait_duration |
用戶端在發出任何尋找雜湊要求前，必須等待的最短時間。如果未設定這個欄位，用戶端可以隨時發出要求。 |
negative_cache_duration |
對於要求的實體不符合威脅清單，快取回應的時間長度。 |
FindThreatMatchesRequest
要求檢查項目是否符合清單。
| 欄位 | |
|---|---|
client |
用戶端中繼資料。 |
threat_info |
要檢查是否相符的清單和項目。 |
FindThreatMatchesResponse
| 欄位 | |
|---|---|
matches[] |
威脅清單相符。 |
ListThreatListsResponse
| 欄位 | |
|---|---|
threat_lists[] |
客戶可下載的清單。 |
PlatformType
平台類型。
| 列舉 | |
|---|---|
PLATFORM_TYPE_UNSPECIFIED |
不明平台。 |
WINDOWS |
威脅 Windows 的程度。 |
LINUX |
對 Linux 造成的威脅。 |
ANDROID |
對 Android 造成的威脅。 |
OSX |
對 OS X 造成的威脅。 |
IOS |
對 iOS 的威脅。 |
ANY_PLATFORM |
威脅至少針對一個定義平台。 |
ALL_PLATFORMS |
對所有定義平台構成的威脅。 |
CHROME |
對 Chrome 造成的威脅。 |
RawHashes
以雜湊格式 (前置字元長度為特定長度) 呈現的未壓縮威脅項目。雜湊的大小介於 4 到 32 位元組之間。大多數的雜湊值長度為 4 個位元組，但如果雜湊值與熱門網址的雜湊值相衝突，則會變長。
用於將 ThreatEntrySet 傳送至不支援壓縮的用戶端，或是將非 4 個位元組的雜湊傳送至支援壓縮的用戶端。
| 欄位 | |
|---|---|
prefix_size |
以下每個前置字串編碼的位元組數。這個欄位的長度可從 4 (最短前置字串) 到 32 (完整 SHA256 雜湊) 之間任意調整。 |
raw_hashes |
以二進位格式連結的雜湊值，會連結成一個長字串。雜湊會依字母順序排列。對於 JSON API 使用者，雜湊會採用 base64 編碼。 |
RawIndices
從本機清單中移除的一組原始索引。
| 欄位 | |
|---|---|
indices[] |
要從字典順序排序的本機清單中移除的索引。 |
RiceDeltaEncoding
Rice-Golomb 編碼資料。用於傳送壓縮過的 4 位元雜湊或壓縮過的移除索引。
| 欄位 | |
|---|---|
first_value |
已編碼資料中第一個項目的偏移量，或如果只編碼單一整數，則為該單一整數的值。如果欄位為空白或缺少，則假設為零。 |
rice_parameter |
Golomb-Rice 參數，介於 2 到 28 之間的數字。如果 |
num_entries |
在已編碼資料中，差異編碼的項目數量。如果只編碼單一整數，這個值會設為零，而單一值會儲存在 |
encoded_data |
使用 Golomb-Rice 編碼器編碼的已編碼差異值。 |
ThreatEntry
個別威脅，例如惡意網址或其雜湊表示法。請只設定其中一個欄位。
| 欄位 | |
|---|---|
hash |
雜湊前置字串，包含 SHA256 雜湊的前 4 到 32 個位元組。這個欄位為二進位格式。對於 JSON 要求，雜湊會採用 base64 編碼。 |
url |
網址。 |
digest |
以 SHA256 格式呈現的可執行檔摘要。此 API 支援二進位和十六進位摘要。如果是 JSON 要求，摘要會採用 base64 編碼。 |
ThreatEntryMetadata
與特定威脅項目相關聯的中繼資料。客戶端應知道與每種威脅類型相關聯的中繼資料鍵/值組合。
| 欄位 | |
|---|---|
entries[] |
中繼資料項目。 |
MetadataEntry
單一中繼資料項目。
| 欄位 | |
|---|---|
key |
中繼資料項目鍵。對於 JSON 要求，鍵會採用 base64 編碼。 |
value |
中繼資料項目值。對於 JSON 要求，值會採用 base64 編碼。 |
ThreatEntrySet
應在用戶端的本機資料庫中新增或移除的威脅。
| 欄位 | |
|---|---|
compression_type |
這個集合中項目的壓縮類型。 |
raw_hashes |
原始的 SHA256 格式項目。 |
raw_indices |
本機清單的原始移除索引。 |
rice_hashes |
使用 Golomb-Rice 編碼，對 SHA256 格式項目的 4 個位元組前置字元進行編碼。雜湊值會轉換為 uint32，並以遞增順序排序，然後以差分編碼並儲存為 encoded_data。 |
rice_indices |
使用 Golomb-Rice 編碼，將經過編碼的本地字典排序清單索引編碼。用於傳送壓縮的移除索引。移除索引 (uint32) 會以遞增順序排序，然後以差分編碼方式編碼並儲存為 encoded_data。 |
ThreatEntryType
可能造成威脅的項目類型。威脅清單是單一類型項目的集合。
| 列舉 | |
|---|---|
THREAT_ENTRY_TYPE_UNSPECIFIED |
未指明 |
URL |
網址。 |
EXECUTABLE |
可執行的程式。 |
ThreatInfo
當用戶端在威脅清單中檢查是否有相符項目時，提交的與一或多個威脅相關的資訊。
| 欄位 | |
|---|---|
threat_types[] |
要檢查的威脅類型。 |
platform_types[] |
要檢查的平台類型。 |
threat_entry_types[] |
要檢查的項目類型。 |
threat_entries[] |
要檢查的威脅項目。 |
ThreatListDescriptor
說明個別威脅清單。清單由三個參數定義：威脅類型、威脅鎖定的平台類型，以及清單中的項目類型。
| 欄位 | |
|---|---|
threat_type |
清單項目所造成的威脅類型。 |
platform_type |
清單項目指定的平台類型。 |
threat_entry_type |
清單中包含的項目類型。 |
ThreatMatch
在安全瀏覽威脅清單中查看威脅項目時，系統會比對這項資訊。
| 欄位 | |
|---|---|
threat_type |
與此威脅相符的威脅類型。 |
platform_type |
與此威脅相符的平台類型。 |
threat_entry_type |
與此威脅相符的威脅項目類型。 |
threat |
與此威脅相符的威脅。 |
threat_entry_metadata |
與這項威脅相關的選用中繼資料。 |
cache_duration |
傳回相符項目的快取生命週期。用戶端不得將此回應快取超過這個時間長度，以免誤報。 |
ThreatType
威脅類型。
| 列舉 | |
|---|---|
THREAT_TYPE_UNSPECIFIED |
未知。 |
MALWARE |
惡意軟體威脅類型。 |
SOCIAL_ENGINEERING |
社交工程威脅類型。 |
UNWANTED_SOFTWARE |
垃圾軟體威脅類型。 |
POTENTIALLY_HARMFUL_APPLICATION |
可能有害的應用程式威脅類型。 |