キャッシュ

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

キャッシュについて

クライアントの帯域幅の使用量を減らし、トラフィックの急増から 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 リクエストを発行しないようにする必要があります。