このページは Cloud Translation API によって翻訳されました。

キャッシュ

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

キャッシュについて

クライアント帯域幅の使用量を減らし、トラフィックの急増から 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

詳細な例については、表のヘッダー内のリクエストリンクとレスポンスリンクをクリックします。

URL チェック threatMatch リクエスト	URL 一致 threatMatch レスポンス	キャッシュ保存動作
"threatEntries": [ {"url": "http://www.urltocheck.org/"} ]	"matches": [{ "threat": {"url": "http://www.urltocheck.org/"}, "cacheDuration": "300.000s" }]	一致クライアントは、URL http://www.urltocheck.org/ を含む新しい `threatMatches` リクエストを送信する前に 5 分間待機する必要があります。

Update API

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

ポジティブキャッシュ

クライアントが特定の安全でないフルハッシュの状態について繰り返し尋ねるのを防ぐために、返される ThreatMatch にはプラスのキャッシュ期間（cacheDuration フィールドによって定義）が含まれます。これは、フルハッシュが安全でないとみなされる時間です。

ネガティブキャッシュ

クライアントが特定の安全なハッシュの状態を繰り返し確認しないようにするには、各 fullHashes レスポンスで、リクエストされた接頭辞の負のキャッシュ期間（negativeCacheDuration フィールドによって定義）を定義します。この期間は、リクエストされた接頭辞を含む完全なハッシュが、リクエストされたリストにとって安全であるとみなされる期間を示します（ただし、サーバーから安全でないものとして返されたものは除きます）。このキャッシュ保存が特に重要になるのは、大量のトラフィックを受信する安全な URL とハッシュプレフィックスが競合することにより発生する可能性のあるトラフィック過負荷を防止するためです。

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

クライアントが URL の状態を確認する際、まず完全なハッシュが計算されます。ローカルデータベースに完全なハッシュの接頭辞が存在する場合、クライアントは、サーバーに対して fullHashes リクエストを行う前に、キャッシュを参照する必要があります。

まず、クライアントがキャッシュヒットを確認する必要があります。対象のハッシュ全体に対して期限切れでないポジティブキャッシュエントリが存在する場合は、安全とはみなされません。ポジティブキャッシュエントリが期限切れになった場合、クライアントは関連付けられたローカルプレフィックスの fullHashes リクエストを送信する必要があります。プロトコルにより、サーバーがフルハッシュを返す場合は安全でないとみなされます。そうでない場合は安全と見なされます。

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

キャッシュの更新

fullHashes レスポンスを受け取るたびにクライアントキャッシュを更新する必要があります。cacheDuration フィールドに従って、フルハッシュのポジティブキャッシュエントリを作成または更新する必要があります。ハッシュプレフィックスの負のキャッシュ期間も、レスポンスの negativeCacheDuration フィールドに従って作成または更新する必要があります。

後続の fullHashes リクエストで、現在肯定的にキャッシュされているフルハッシュが返されない場合、クライアントはポジティブなキャッシュエントリを削除する必要はありません。実際、これは問題ではありません。正のキャッシュ期間は、通常、偽陽性をすばやく修正するために短い（数分）からです。

状況の例

次の例では、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 分で、別の fullHashes リクエストを送信することなく、完全長ハッシュ H（example.com/）を安全でないとみなされる期間をクライアントに示します。5 分後に、クライアントが example.com/ に再度アクセスする場合は、そのプレフィックス h（example.com/）に対して別の fullHashes リクエストを発行する必要があります。クライアントは新しいレスポンスごとにハッシュプレフィックスの負のキャッシュ期間をリセットする必要があります。

1 時間のネガティブキャッシュ期間は、同じプレフィックスの h（example.com/）を共有する H(example.com/) 以外の他のすべてのフルレングスハッシュをどのくらいの時間が安全であるのかをクライアントに知らせます。1 時間の間、h(URL) = h(example.com/) のようなすべての URL は安全であると見なされ、fullHashes リクエストは発生しません（H(URL) != H（example.com/）であると仮定）。

fullHashes レスポンスにゼロの一致が含まれ、ネガティブキャッシュ期間が設定されている場合、クライアントは、指定されたネガティブキャッシュ期間について、リクエストされた接頭辞に対して fullHashes リクエストを発行してはなりません。

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

例: fullHashes.find