總覽
使用 Update API 可讓用戶端應用程式下載 Safe Browsing 清單的雜湊版本，並儲存至本機資料庫中。接著就可以在本機檢查網址。只有在 用戶端必須將要求傳送至安全瀏覽伺服器，才能驗證 是否將該網址納入「安全瀏覽」清單。
使用 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 欄位
會結合識別 (名稱)「安全瀏覽」清單。本範例有一個清單：
惡意軟體/WINDOWS/URL。傳送請求之前，請確認您指定的類型組合有效
(請參閱安全瀏覽清單)。
用戶端狀態
state 欄位會保留安全瀏覽清單的目前用戶端狀態。(用戶端狀態會在 newClientState 欄位的
threatListUpdates.fetch 回應)。
針對初始更新，請將 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 欄位會保留新版 Safe Browsing 清單的新用戶端狀態。用戶端必須儲存新的用戶端狀態，才能在後續的更新要求中使用 (state 欄位的
threatListUpdates.fetch 要求
或是顯示「clientStates」欄位中
fullHashes.find 要求)。
檢查碼機制
用戶端可透過總和檢查碼驗證本機資料庫是否有任何損毀情形。如果總和檢查碼不相符，用戶端就必須清除資料庫，並以空白 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。傳送請求前，請確定您的類型組合
是否有效 (請參閱安全瀏覽清單)。
威脅雜湊前置字串
ThreatEntry 陣列包含您要檢查的網址的雜湊前置字串。
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" }
相符組合
Match 物件會傳回兩個雜湊前置字串相符的完整長度雜湊。網址 與這些雜湊對應的一律視為不安全。系統未找到第三個雜湊前置字串的相符項目，因此不會傳回任何內容；系統會將對應此雜湊前置字串的網址視為安全。
請注意，這個範例會將一個完整雜湊和一個雜湊前置字元進行比對。不過 對應至同一個雜湊前置字元的多個完整雜湊。
中繼資料
threatEntryMetadata 為選填欄位，提供威脅的其他相關資訊
比對。目前，中繼資料可用於 MALWARE/WINDOWS/URL 安全瀏覽清單 (請參閱「中繼資料」)。
快取時間長度
cacheDuration 和 negativeCacheDuration 欄位會指出金額
都會產生雜湊值
視為不安全或安全 (請參閱「快取」一節)。
最短等待時間
minimumWaitDuration 欄位表示用戶端必須先等待 300 秒 (5 分鐘)
再傳送一次 FullHash 要求。請注意，回應中可能會包含等候時間 (請參閱「要求頻率」)。