キャッシュ

このドキュメントは、次のメソッドに適用されます。

キャッシュについて

クライアントの帯域幅の使用量を減らし、トラフィックの急増から Google を保護するには、Lookup API と Update API の両方のクライアントが脅威データのローカルキャッシュを作成して維持する必要があります。Lookup API はキャッシュを使用して、クライアントが Google に送信する uris.search リクエストの数を減らします。Update API では、クライアントが Google に送信する hashes.search リクエストの数を減らすためにキャッシュが使用されます。各 API のキャッシュプロトコルの概要は次のとおりです。

Lookup API

Lookup API のクライアントは、返された各 ThreatUrl 項目を expireTime フィールドで定義された時刻までキャッシュする必要があります。その後、クライアントはサーバーに後続の uris.search リクエストを行う前にキャッシュを参照する必要があります。以前に返された ThreatUrl のキャッシュエントリがまだ期限切れになっていない場合、クライアントはそのアイテムがまだ安全でないとみなす必要があります。ThreatUrl 項目をキャッシュすると、クライアントが行う API リクエストの数を減らすことができます。

Update API

Update API を使用して Google に送信される hashes.search リクエストの総数を減らすには、クライアントでローカルキャッシュを維持する必要があります。この API では、ポジティブとネガティブの 2 種類のキャッシュが確立されます。

ポジティブキャッシュ

クライアントが、特定の安全でない完全ハッシュの状態について繰り返し問い合わせることを防ぐため、返されるそれぞれの ThreatHash にはポジティブキャッシュ時間（expireTime フィールドで定義）が含まれます。完全なハッシュは、この時間まで安全ではないとみなすことができます。

ネガティブキャッシュ

クライアントが特定の安全な完全ハッシュの状態について繰り返し問い合わせることを防ぐため、レスポンスではリクエストされた接頭辞（negativeExpireTime フィールドで定義）のネガティブのキャッシュ期間を定義します。リクエストされたプレフィックスを持つすべての完全なハッシュは、リクエストされた脅威タイプに対して安全でないとみなされます。このキャッシュは、多くのトラフィックを受信する安全な URL とのハッシュプレフィックスの競合によってトラフィックが過負荷になるのを防ぐために特に重要です。

キャッシュに関するコンサルティング

クライアントが URL の状態を確認するときは、まず完全なハッシュを計算します。完全なハッシュのプレフィックスがローカルデータベースに存在する場合、クライアントはサーバーに hashes.search リクエストを行う前にキャッシュを参照する必要があります。

まず、クライアントがキャッシュヒットを確認する必要があります。関心のあるハッシュ全体に対するポジティブキャッシュエントリの有効期限が切れていない場合は、安全でないとみなす必要があります。ポジティブキャッシュエントリが期限切れになった場合、クライアントは関連するローカルプレフィックスの hashes.search リクエストを送信する必要があります。プロトコルごとに、サーバーが完全なハッシュを返す場合は、安全ではないとみなされます。それ以外の場合は、安全と見なされます。

完全なハッシュのポジティブキャッシュエントリがない場合、クライアントはネガティブキャッシュヒットをチェックする必要があります。関連付けられたローカルプレフィックスに有効期限が切れていないネガティブキャッシュエントリが存在する場合、完全なハッシュは安全とみなされます。ネガティブキャッシュエントリが期限切れになった場合、または存在しない場合、クライアントは関連付けられたローカルプレフィックスの hashes.search リクエストを送信し、レスポンスを通常と解釈します。

キャッシュの更新

クライアントキャッシュは、hashes.search レスポンスを受信するたびに更新されます。expireTime フィールドごとにポジティブキャッシュエントリを作成または更新する必要があります。ハッシュプレフィックスのネガティブキャッシュ期間も、レスポンスの negativeExpireTime フィールドごとに作成または更新する必要があります。

後続の hashes.search リクエストが現在キャッシュされている完全なハッシュを返さない場合、クライアントはポジティブキャッシュのエントリを削除する必要はありません。誤判定を迅速に修正できるように、通常はポジティブのキャッシュ時間は短い（数分）ため、これは実際には問題にはなりません。

例

次の例では、h(url) が URL のハッシュプレフィックスで、H(url) が 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 分間）は、hashes.search リクエストを送信することなくフルレングスのハッシュ H（example.com/）が安全ではないとみなす時間をクライエントに伝えます。5 分後に、クライアントがもう一度 example.com/にアクセスする場合、クライアントはそのプレフィックス h（example.com/）の別の hashes.search リクエストを発行する必要があります。クライアントは、新しいレスポンスごとにハッシュプレフィックスのネガティブキャッシュの有効期限をリセットする必要があります。

ネガティブキャッシュの時間（1 時間）は、h（example.com/）の同じプレフィックスを共有する H（example.com/）以外のすべてのフルレングスハッシュを安全とみなす時間をクライアントに伝えます。1 時間の間は、h（URL）= h（example.com/）のようなすべてのURL は安全と見なされるため、hashes.search リクエストにはなりません（H（URL）！= H（example.com/）と想定）。

fullHashes レスポンスに 0 の一致が含まれ、ネガティブキャッシュの有効期限が設定されている場合、クライアントは指定されたネガティブキャッシュ時間のリクエストに対して hashes.search リクエストを発行しません。

hashes.search レスポンスに 1 つ以上の一致が含まれている場合でも、レスポンス全体にネガティブキャッシュの有効期限が設定されます。その場合、1 つの完全なハッシュのキャッシュ有効期限は、クライアントが特定のフルレングスのハッシュを安全でないとみなす必要がある時間を示します。ThreatHash キャッシュ期間が経過した後、リクエストされた URL がキャッシュ内の既存のフルレングスハッシュと一致する場合、クライアントはハッシュプレフィックスの hashes.search リクエストを発行します。その場合、ネガティブキャッシュの期間は適用されません。レスポンスのネガティブキャッシュ期間は、hashes.search レスポンスに存在しないフルレングスハッシュにのみ適用されます。レスポンスに存在しない完全な長さのハッシュの場合、クライアントはネガティブキャッシュ期間が経過するまで hashes.search リクエストを発行しないようにする必要があります。