總覽
Update API 可讓用戶端應用程式下載經雜湊處理的安全瀏覽清單版本,以便儲存在本機資料庫中。接著,系統即可在本機檢查網址。只有在本機資料庫中發現相符內容時,用戶端才需傳送要求給安全瀏覽伺服器,驗證該網址是否已納入安全瀏覽清單。
使用 Update API 前,您必須先設定本機資料庫。您可以使用安全瀏覽功能提供 Go 套件,詳情請參閱本機資料庫下方的「資料庫設定」一節。
更新本機資料庫
為保持最新狀態,用戶端必須定期更新本機資料庫中的安全瀏覽清單。為節省頻寬,用戶端會下載網址的雜湊前置字串,而非原始網址。舉例來說,如果「www.badurl.com/」在安全瀏覽清單上,用戶端會下載該網址的 SHA256 雜湊前置字串,而非網址本身。在大多數情況下,雜湊前置字串的長度為 4 個位元組,也就是說,在壓縮前下載單一清單項目的平均頻寬費用為 4 個位元組。
如要更新本機資料庫中的安全瀏覽清單,請將 HTTP POST
要求傳送至 threatListUpdates.fetch 方法:
- HTTP
POST
要求包含要更新的清單名稱,以及各種用戶端限制,以因應記憶體和頻寬限制。 - HTTP
POST
回應會傳回完整更新或部分更新。回應可也會傳回最短等待時間長度。
範例: ThreatListUpdates.fetch
HTTP POST 要求
在以下範例中,系統會要求更新單一安全瀏覽清單。
要求標頭
要求標頭包含要求網址和內容類型。請記得將網址中的 API_KEY
替換成您的 API 金鑰。
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
要求主體
要求主體包含用戶端資訊 (ID 和版本) 和更新資訊 (清單名稱、清單狀態和用戶端限制)。詳情請參閱 threatListUpdates.fetch 要求主體和遵循程式碼範例的說明。
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "listUpdateRequests": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "state": "Gg4IBBADIgYQgBAiAQEoAQ==", "constraints": { "maxUpdateEntries": 2048, "maxDatabaseEntries": 4096, "region": "US", "supportedCompressions": ["RAW"] } }] }
客戶資訊
clientID
和 clientVersion
欄位應用於識別用戶端實作,而非個別使用者。(用戶端資訊會用於伺服器端記錄中。您可以為用戶端 ID 選擇任何名稱,但我們建議您選擇能代表客戶真實身分的名稱,例如您的公司名稱,以全大寫的字母顯示,且只用一個字。)
安全瀏覽清單
系統會將 threatType
、platformType
和 threatEntryType
欄位合併,以識別安全瀏覽清單 (名稱)。本範例有一份清單:MALWARE/WINDOWS/URL。傳送要求之前,請先確認您指定的類型組合有效 (請參閱安全瀏覽清單)。
用戶端狀態
state
欄位會保留安全瀏覽清單目前的用戶端狀態。(用戶端狀態會在 threatListUpdates.fetch 回應的 newClientState
欄位中傳回)。針對初始更新,請將 state
欄位留空。
大小限制
maxUpdateEntries
欄位會指定用戶端可管理的更新總數 (在本例中為 2048)。maxDatabaseEntries
欄位會指定本機資料庫可管理的項目總數 (在本例中為 4096)。用戶端應該設定大小限制來保護記憶體和頻寬限制,並避免清單增加。詳情請參閱更新限制。
支援的壓縮
supportedCompressions
欄位會列出用戶端支援的壓縮類型。在此範例中,用戶端僅支援未壓縮的原始資料。不過,安全瀏覽功能支援其他壓縮類型 (請參閱壓縮)。
HTTP POST 回應
在此範例中,回應會使用要求的壓縮類型,為安全瀏覽清單傳回部分更新。
回應標頭
回應標頭包含 HTTP 狀態碼和內容類型。接收 HTTP/200 以外的狀態碼的用戶端必須進入輪詢模式 (請參閱要求頻率)。
HTTP/1.1 200 OK Content-Type: application/json
回應主體
回應主體包含更新資訊,例如清單名稱、回應類型、要套用至本機資料庫的新增和移除作業、新的用戶端狀態以及總和檢查碼。在此範例中,回應也包含最短等待時間長度。詳情請參閱 threatListUpdates.fetch 回應主體和遵循程式碼範例的說明。
{ "listUpdateResponses": [{ "threatType": "MALWARE", "threatEntryType": "URL", "platformType": "WINDOWS", "responseType" : "PARTIAL_UPDATE", "additions": [{ "compressionType": "RAW", "rawHashes": { "prefixSize": 4, "rawHashes": "rnGLoQ==" } }], "removals": [{ "compressionType": "RAW", "rawIndices": { "indices": [0, 2, 4] } }], "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd", "checksum": { "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM=" } }], "minimumWaitDuration": "593.440s" }
資料庫更新
responseType
欄位會顯示部分或完整更新。在此範例中,系統會傳回部分更新,因此回應中同時包含新增和移除。可以新增多組新增項目,但只能移除一組移除項目 (請參閱資料庫更新的相關說明)。
新用戶端狀態
newClientState
欄位會保留新更新的安全瀏覽清單新用戶端狀態。用戶端必須儲存新的用戶端狀態,才能用於後續更新要求 (threatListUpdates.fetch 要求中的 state
欄位,或 fullHashes.find 要求中的 clientStates
欄位)。
檢查碼機制
檢查碼可讓用戶端驗證本機資料庫未發生任何損毀的情形。如果檢查碼不相符,用戶端必須清除資料庫,並以空白的 state
欄位重新發出更新。不過,在這種情況下,用戶端仍須遵循更新週期的時間間隔 (請參閱要求頻率)。
最短等待時間
minimumWaitDuration
欄位表示用戶端必須先等待 593.44 秒 (9.89 分鐘),才能傳送其他更新要求。請注意,回應不一定會包含等候期間 (請參閱要求頻率)。
檢查網址
如要檢查特定網址是否列在安全瀏覽清單上,用戶端必須先計算網址的雜湊和雜湊前置字串 (請參閱網址和雜湊)。接著,用戶端會查詢本機資料庫,確認是否存在相符項目。如果本機資料庫中「沒有」雜湊前置字串,系統會將該網址視為安全網址 (而不是安全瀏覽清單)。
如果本機資料庫中「有」雜湊前置字串 (雜湊前置字串衝突),用戶端必須將雜湊前置字串傳送至安全瀏覽伺服器進行驗證。伺服器會傳回所有包含指定雜湊前置字串的完整 SHA 256 雜湊。 如果其中一個完整雜湊值與相關網址的完整雜湊相符,系統就會將該網址視為不安全。如果完整雜湊值都與問題網址的完整雜湊值不符,系統就會將該網址視為安全網址。
Google 不會知道你要檢查的網址。Google 會知道網址的雜湊前置字串,但雜湊前置字元無法提供實際網址的相關資訊。
如要檢查網址是否列在安全瀏覽清單上,請將 HTTP POST
要求傳送至 fullHashes.find 方法:
- HTTP
POST
要求最多可包含 500 個威脅項目。 - HTTP
POST
要求包含要檢查網址的雜湊前置字串。我們建議用戶端將多個威脅項目批次處理為單一要求,以降低頻寬用量。 - HTTP
POST
回應會傳回相符的完整雜湊值,以及正負快取持續時間的正數和負數。回應可能也會傳回最短等待時間長度。
範例:fullHashes.find
HTTP POST 要求
在以下範例中,系統會傳送兩個安全瀏覽清單和三個雜湊前置字串的名稱,用於比較和驗證。
要求標頭
要求標頭包含要求網址和內容類型。請記得將網址中的 API_KEY
替換成您的 API 金鑰。
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
要求主體
要求主體包含用戶端資訊 (ID 和版本)、用戶端狀態,以及威脅資訊 (清單名稱和雜湊前置字串)。如果是 JSON 要求,雜湊前置字串必須以 Base64 編碼格式傳送。詳情請參閱 fullHashes.find 要求主體和程式碼範例。
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "clientStates": [ "ChAIARABGAEiAzAwMSiAEDABEAE=", "ChAIAhABGAEiAzAwMSiAEDABEOgH" ], "threatInfo": { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "platformTypes": ["WINDOWS"], "threatEntryTypes": ["URL"], "threatEntries": [ {"hash": "WwuJdQ=="}, {"hash": "771MOg=="}, {"hash": "5eOrwQ=="} ] } }
客戶資訊
clientID
和 clientVersion
欄位應用於識別用戶端實作,而非個別使用者。(用戶端資訊會用於伺服器端記錄中。您可以為用戶端 ID 選擇任何名稱,但我們建議您選擇能代表客戶真實身分的名稱,例如您的公司名稱,以全大寫的字母顯示,且只用一個字。)
所有用戶端狀態
clientStates
欄位會保留用戶端本機資料庫中「所有」安全瀏覽清單的用戶端狀態。(用戶端狀態會在 threatListUpdates.fetch 回應的 newClientState
欄位中傳回)。
安全瀏覽清單
threatTypes
、platformTypes
和 threatEntryTypes
欄位會結合以識別安全瀏覽清單 (名稱)。此範例有兩個清單:MALWARE/WINDOWS/URL 和 SOCIAL_ENGINEERING/WINDOWS/URL。傳送要求之前,請先確認您指定的類型組合有效 (請參閱安全瀏覽清單)。
威脅雜湊前置字串
ThreatEntries 陣列包含要檢查的網址雜湊前置字串,hash
欄位必須包含本機資料庫中的確切雜湊前置字串。舉例來說,如果本機雜湊前置字串是 4 個位元組,威脅項目的長度必須為 4 個位元組。如果本機雜湊前置字串的長度為 7 個位元組,威脅項目的長度必須為 7 個位元組。
在本範例中,要求包含三個雜湊前置字串。系統會將這三個前置字串與每個安全瀏覽清單進行比較,以判斷是否具有相符的完整雜湊。
注意:Update API 和 FullHashes.find 方法應一律使用 hash
欄位,而非 URL
欄位 (請參閱 ThreatEntry)。
HTTP POST 回應
在以下範例中,回應會傳回由安全瀏覽清單整理的相符資料,以及快取和等待時間長度。
回應標頭
回應標頭包含 HTTP 狀態碼和內容類型。如果用戶端接收到 HTTP/200 以外的狀態碼,就必須輪詢 (請參閱要求頻率)。
HTTP/1.1 200 OK Content-Type: application/json
回應主體
回應主體會包含比對資訊 (清單名稱和完整長度雜湊、中繼資料 (如有),以及快取持續時間)。在此範例中,回應主體也包含最短等待時間長度。詳情請參閱 fullHashes.find 回應主體和按照程式碼範例操作的說明。
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4=" }, "threatEntryMetadata": { "entries": [{ "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==", // base64-encoded "malware_threat_type" "value": "TEFORElORw==" // base64-encoded "LANDING" }] }, "cacheDuration": "300.000s" }, { "threatType": "SOCIAL_ENGINEERING", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA=" }, "threatEntryMetadata": { "entries": [] }, "cacheDuration": "300.000s" }], "minimumWaitDuration": "300.000s", "negativeCacheDuration": "300.000s" }
相符
「符合」物件會針對兩個雜湊前置字串傳回相符的完整雜湊值。對應至這些雜湊的網址會視為不安全的網址。找不到與第三個雜湊前置字串相符的項目,因此不會傳回任何內容;系統會將對應至這個雜湊前置字串的網址視為安全。
請注意,本例將一個完整雜湊值與一個雜湊前置字串進行比對,但可能有多個完整雜湊對應至同一個雜湊前置字串。
Metadata
threatEntryMetadata
為選用欄位,可提供與威脅比對相關的額外資訊。目前,MALWARE/WINDOWS/網址安全瀏覽清單可以使用中繼資料 (請參閱中繼資料)。
快取持續時間
cacheDuration
和 negativeCacheDuration
欄位會指出雜湊必須視為不安全或安全的時間 (請參閱快取一節)。
最短等待時間
minimumWaitDuration
欄位表示用戶端必須先等待 300 秒 (5 分鐘),才能傳送另一個 FullHash 要求。請注意,回應不一定會包含等候期間 (請參閱要求頻率)。