總覽
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 要求。請注意，回應不一定會包含等候期間 (請參閱要求頻率)。