快取中

本文件適用於下列方法：

• Lookup API (v4)： threatMatches.find
• Update API (v4)： fullHashes.find

關於快取

如要降低用戶端頻寬用量，同時避免 Google 服務流量突然攀升，請同時執行 須有 Lookup API 和 Update API 才能建立並維護威脅資料的本機快取。 如果是 Lookup API，系統會使用快取來減少 threatMatches 的數量 用戶端傳送給 Google 的要求如果是 Update API，系統會使用快取減少 用戶端傳送給 Google 的 fullHashes 要求。各個 API 的快取通訊協定 。

Lookup API

Lookup API 的用戶端應在指定的期間內快取每個傳回的 ThreatMatch 項目 取決於其快取時間長度接著用戶端必須先查詢快取，才能執行後續作業 對伺服器提出 threatMatches 要求。如果先前傳回的 ThreatMatch 的快取持續時間 尚未過期，客戶應認定該項目仍然不安全。正在快取 ThreatMatch 個項目 可減少用戶端提出的 API 要求數量。

例如： Threat 比對.find

如要查看完整範例，請點選表格標題中的要求與回應連結。

"threatEntries": [
 {"url": "http://www.urltocheck.org/"}
]

"matches": [{
 "threat": {"url": "http://www.urltocheck.org/"},
 "cacheDuration": "300.000s"
}]

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(網址)。

現在，假設用戶端 (快取空白) 造訪 example.com/，並查看 h(example.com/) 就能儲存內容用戶端要求雜湊前置字元 h(example.com/) 的完整雜湊值 然後收到完整的雜湊 H(example.com/) 和正快取時長 5 快取時間長度為 1 小時

5 分鐘的正快取持續時間可讓用戶端瞭解完整雜湊值的長度 您必須將 H(example.com/) 視為不安全，無須再次傳送 fullHashes 要求。5 後 分鐘，若用戶端針對該前置字串 h(example.com/) 發出另一個 fullHashes 要求， 再次造訪 example.com/用戶端應重設雜湊前置字串的負快取持續時間 依據新的回覆

1 小時的負快取時間長度會向用戶端說明所有其他完整雜湊值的長度 除了使用相同前置字元 h(example.com/) 的 H(example.com/) 以外，也必須視為安全。適用對象 時，每個網址 h(URL) = h(example.com/) 都必須視為安全；且 因此，不會產生 fullHashes 要求 (假設 H(URL) != H(example.com/))。

如果 fullHashes 回應中沒有任何相符項目，且快取的持續時間已設定負數， 用戶端不得針對任何指定的前置碼，發出任何 fullHashes 要求 快取時間長度為負值。

如果 fullHashes 回應包含一或多個相符項目，系統仍會設定負數的快取持續時間 直到獲得完整回應在此情況下，單一完整雜湊的快取持續期間代表 用戶端必須假設對特定完整雜湊值不安全。ThreatMatch 快取之後 過了這段時間後，用戶端必須向fullHashes 該雜湊前置字元 (如果要求的網址與快取中現有的完整長度雜湊相符)。在這個例子中 這種做法就不適用負荷快取時間長度。回應的負快取時長僅適用 到 fullHashes 回應中沒有的完整雜湊。對於 未出現在回應中，用戶端必須避免發出任何 fullHashes 要求 直到快取持續時間變為負值為止。

範例：fullHashes.find

如要查看完整範例，請點選表格標題中的要求與回應連結。

"threatEntries": [
  {"hash": "0xaaaaaaaa"}
]

"matches": [],
"negativeCacheDuration": "3600.000s"

"threatEntries": [
  {"hash": "0xbbbbbbbb"}
]

"matches": [
 "threat": {"hash": "0xbbbbbbbb0000..."}
 "cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"

"threatEntries": [
  {"hash": "0xcccccccc"}
]

"matches": [
 "threat": {"hash": "0xccccccccdddd..."},
 "cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"