本文件適用於下列方法：
關於快取
為降低用戶端頻寬用量並保護 Google 不受流量突然增加的情形，Lookup API 和 Update API 的用戶端必須建立並維護威脅資料的本機快取。針對 Lookup API，系統會使用快取減少用戶端傳送至 Google 的 threatMatches 要求數量。針對 Update API，系統使用快取來減少用戶端傳送給 Google 的 fullHashes 要求數量。以下說明各個 API 的快取通訊協定。
Lookup API
Lookup API 的用戶端應依據其 cacheDuration 欄位所定義的持續時間，快取每個傳回的 ThreatMatch 項目。接著，用戶端需要先查詢快取，才能向伺服器提出後續 threatMatches 要求。如果先前傳回的 ThreatMatch 快取持續時間尚未過期，用戶端會假設該項目仍不安全。快取 ThreatMatch 項目可能會減少用戶端發出的 API 要求數量。
範例： ThreatMatch.find
按一下表格標頭中的要求與回應連結即可查看完整範例。
| 網址檢查 威脅符合要求 |
網址比對 威脅相符回應 |
快取行為 |
|---|---|---|
"threatEntries": [
{"url": "http://www.urltocheck.org/"}
]
|
"matches": [{
"threat": {"url": "http://www.urltocheck.org/"},
"cacheDuration": "300.000s"
}]
|
進行比對。 用戶端必須等待 5 分鐘，才能傳送含有 http://www.urltocheck.org/ 網址的新 threatMatches 要求。 |
Update API
如要減少使用 Update API 傳送至 Google 的 fullHashes 要求總數，用戶端必須維護本機快取。此 API 會建立兩種快取：正數和負數。
正面快取
為了避免用戶端重複詢問特定「不安全的」完整雜湊狀態，每個傳回的 ThreatMatch 都包含正快取持續時間 (由 cacheDuration 欄位定義)，用來表示將完整雜湊視為不安全的時間長度。
負面快取
為避免用戶端重複詢問特定「安全」完整雜湊的狀態，每個 fullHashes 回應都會針對要求的前置字串 (由 negativeCacheDuration 欄位定義) 定義負的快取持續時間。這個時間長度代表要求清單中所有包含要求前置字元的所有完整雜湊都視為安全的時間長短，但伺服器傳回的不安全字元除外。這個快取功能尤其重要，因為可以利用接收大量流量的安全網址，避免雜湊前置字串衝突造成的流量超載。
諮詢快取
當用戶端想檢查網址狀態時，會先計算其完整雜湊。如果本機資料庫中有完整的雜湊前置字串，用戶端應先查詢其快取，然後再向伺服器提出 fullHashes 要求。
首先，客戶應檢查快取是否正好。如果完整雜湊中有未過期的正快取項目，則應視為不安全。如果正快取項目已過期，用戶端就必須針對相關聯的本機前置字串傳送 fullHashes 要求。根據通訊協定，如果伺服器傳回完整雜湊，就會被視為不安全；否則系統會將其視為安全。
如果完整雜湊沒有陽性快取項目，用戶端應檢查快取是否命中。如果相關聯的本機前置字串有未過期的排除快取項目，系統會將完整雜湊視為安全。如果負快取項目已過期或不存在，用戶端必須針對相關聯的本機前置字串傳送 fullHashes 要求，並照常解讀回應。
更新快取
收到 fullHashes 回應時，應更新用戶端快取。您應根據 cacheDuration 欄位，為完整雜湊建立或更新陽性快取項目。同時也應根據回應的 negativeCacheDuration 欄位建立或更新雜湊前置字串的負快取期間。
如果後續的 fullHashes 要求並未傳回目前為陽性快取的完整雜湊值，用戶端就不需要移除正快取項目。這並非實際做法，因為正值快取持續時間通常較短 (幾分鐘)，以便快速修正誤判情形。
情境示例
在以下範例中，假設 h(url) 是網址的雜湊前置字串，H(url) 則是網址的完整雜湊。也就是說，h(url) = SHA256(url).substr(4), H(url) = SHA256(url)。
現在，假設有空白快取的用戶端造訪 example.com/，並發現 h(example.com/) 位於本機資料庫中。用戶端會要求雜湊前置字串 h(example.com/) 的完整雜湊值，並傳回完整的雜湊 H(example.com/) 雜湊值，以及正快取持續時間為 5 分鐘，負快取持續時間為 1 小時。
若是 5 分鐘的正快取持續時間，會告知用戶端在沒有再次傳送 fullHashes 要求的情況下，完整雜湊 H(example.com/) 存在多久的時間。5 分鐘後，如果用戶端再次造訪 example.com/，用戶端就必須針對該前置字串 h(example.com/) 再次發出 fullHashes 要求。用戶端應根據新的回應，重設雜湊前置字串的負快取期間。
1 小時的負快取持續時間會告知用戶端，具有相同前置字元 h(example.com/) 的所有其他完整雜湊值 (H(example.com/) 除外) 必須視為安全。在 1 小時內，每個網址都必須視為安全，因此不會產生 fullHashes 要求 (假設 H(網址) != H(example.com/))。
如果 fullHashes 回應不含任何相符項目，且您設定了負快取持續時間，則用戶端不得在指定負快取效期內，針對要求的任何前置字串發出任何 fullHashes 要求。
如果 fullHashes 回應包含一或多個相符項目，系統仍會為整個回應設定負值快取持續時間。在這種情況下，單一完整雜湊的快取持續時間表示用戶端必須假設特定完整長度雜湊的不安全時間。過了 ThreatMatch 快取時間長度後，如果要求的網址與快取中現有的完整雜湊值相符，用戶端就必須針對該雜湊前置字串發出 fullHashes 要求，以重新整理完整的雜湊值。在這種情況下，系統就不會套用負值快取持續時間。回應的負快取時間長度僅適用於 fullHashes 回應中沒有的完整雜湊。如果是在回應中沒有的完整雜湊值，用戶端不得在負快取持續時間屆滿前發出任何 fullHashes 要求。
範例：fullHashes.find
按一下表格標頭中的要求與回應連結即可查看完整範例。
| 雜湊前置字串 fullHashes 要求 |
全長雜湊符合 fullHashes 回應 |
快取行為 |
|---|---|---|
"threatEntries": [
{"hash": "0xaaaaaaaa"}
]
|
"matches": [], "negativeCacheDuration": "3600.000s" |
找不到相符的結果。 用戶端不得針對雜湊前置字串 0xaaaaaa 至少一小時傳送任何 fullHashes 要求。任何前置字串為 0xaaaaaa 的雜湊均視為安全一小時。 |
"threatEntries": [
{"hash": "0xbbbbbbbb"}
]
|
"matches": [
"threat": {"hash": "0xbbbbbbbb0000..."}
"cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
|
可能的相符項目。 用戶端應將包含完整雜湊值 0xbbbbbb0000 的網址視為不安全，只有 10 分鐘不安全。用戶端應將雜湊前置字串 0xbbbbbbbbb 保護用法 5 分鐘的所有其他網址視為安全時間 5 分鐘。5 分鐘過後，雜湊前置字串會使排除快取項目過期。由於 0xbbbbbb0000... 的正快取項目尚未過期，用戶端應針對所有雜湊傳送 fullHashes 要求 (該要求除外)。 |
"threatEntries": [
{"hash": "0xcccccccc"}
]
|
"matches": [
"threat": {"hash": "0xccccccccdddd..."},
"cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
|
可能的相符項目。 除非網址的完整雜湊與快取的完整雜湊 0xccccdddd 相符，否則用戶端不得針對雜湊前置字元 0xcccccc 至少 1 小時傳送任何 fullHashes 要求在這種情況下，客戶應將該網址視為不安全的網址 10 分鐘。
完整長度的雜湊會在 10 分鐘後失效。該完整雜湊的任何後續查詢都會觸發新的 fullHashes 要求。 |