このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示する。
このポリシーは、バックエンド リソースからデータをキャッシュに保存し、リソースに対するリクエスト数を削減します。このポリシーを使用すると、アプリが以前と同じ URI にリクエストを送信した場合、そのリクエストをバックエンド サーバーに転送する代わりに、キャッシュに保存されているレスポンスをアプリに返すことができます。ResponseCache ポリシーによってレイテンシとネットワーク トラフィックを削減することで、API のパフォーマンスが向上します。
このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。
API で使用されるバックエンド データが定期的にしか更新されない場合、ResponseCache は非常に便利です。たとえば、10 分間隔で更新される気象レポートを公開する API があるとします。ResponseCache を使用して、更新のたびにキャッシュに保存されたレスポンスが返されるようにすれば、バックエンドに到達するリクエストの数を削減できます。これにより、ネットワーク ホップの数も少なくなります。
汎用の短期キャッシュには、PopulateCache ポリシーの使用を検討してください。このポリシーは、LookupCache ポリシー(キャッシュ エントリの読み取り)と InvalidateCache ポリシー(エントリの無効化)と組み合わせて使用されます。
ResponseCache ポリシーの概要については、次の動画をご覧ください。
サンプル
10 分間のキャッシュ
この例では、キャッシュに保存されたレスポンスを 10 分間保持する方法を説明します。
次の URL にある API を使用しているとします。
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
クエリ パラメータ w
をキャッシュキーとして使用しています。リクエストを受信するたびに、Apigee は w
というクエリ パラメータの値をチェックします。キャッシュ内に有効な(つまり、期限切れでない)レスポンスが存在する場合、キャッシュに保存されているレスポンス メッセージがリクエスト側クライアントに返されます。
ResponseCache ポリシーは、次のように構成されているとします。
<ResponseCache name="ResponseCache"> <CacheKey> <KeyFragment ref="request.queryparam.w" /> </CacheKey> <ExpirySettings> <TimeoutInSeconds>600</TimeoutInSeconds> </ExpirySettings> </ResponseCache>
API プロキシが以下の URL に対するリクエスト メッセージを初めて受信すると、そのリクエストに対するレスポンスがキャッシュに保存されます。10 分以内に 2 回目のリクエストを受信すると、キャッシュ ルックアップが行われます。キャッシュに保存されているレスポンスがアプリに返され、2 回目のリクエストはバックエンド サービスに転送されません。
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
キャッシュ ルックアップをスキップする
次の例では、キャッシュ ルックアップをスキップしてキャッシュを更新します。SkipCacheLookup の使用方法については、こちらの動画もご覧ください。
リクエストパスに含まれるオプションの SkipCacheLookup 条件(構成されている場合)が評価されます。条件が true と評価された場合は、キャッシュ ルックアップをスキップしてキャッシュを更新します。
条件付きキャッシュ更新の一般的な用途は、条件で特定の HTTP ヘッダーを定義し、そのヘッダーによって条件が true と評価されるようにすることです。クライアント アプリケーションでは、当該 HTTP ヘッダーを使ってレスポンス キャッシュを明示的に更新するリクエストを定期的に送信するスクリプトの構成が可能です。
たとえば、次の URL にある API を呼び出すとします。
'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"
プロキシでは、ResponseCache ポリシーが次のように構成されているとします。bypass-cache 条件が true に設定されています。
<ResponseCache name="ResponseCache"> <CacheKey> <KeyFragment ref="request.queryparam.w" /> </CacheKey> <!-- Explicitly refresh the cached response --> <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup> <ExpirySettings> <TimeoutInSeconds>600</TimeoutInSeconds> </ExpirySettings> </ResponseCache>
条件の詳細については、フロー変数と条件をご覧ください。
要素リファレンス
要素リファレンスは、ポリシーの要素と属性を記述します。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1"> <DisplayName>Response Cache 1</DisplayName> <Properties/> <CacheKey> <Prefix/> <KeyFragment ref="request.uri" /> </CacheKey> <Scope>Exclusive</Scope> <ExpirySettings> <ExpiryDate/> <TimeOfDay/> <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds> </ExpirySettings> <CacheResource>cache_to_use</CacheResource> <CacheLookupTimeoutInSeconds/> <ExcludeErrorResponse/> <SkipCacheLookup/> <SkipCachePopulation/> <UseAcceptHeader/> <UseResponseCacheHeaders/> </ResponseCache>
<ResponseCache> 属性
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
次の表に、すべてのポリシーの親要素に共通する属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
name |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗したときにエラーを返す場合は、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name
属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
デフォルト |
なし この要素を省略した場合、ポリシーの |
---|---|
要否 | 省略可 |
タイプ | 文字列 |
<CacheKey> 要素
キャッシュに保存されているデータを参照する一意のポインタを構成します。
キャッシュキーのサイズは 2 KB に制限されています。
<CacheKey> <Prefix>string</Prefix> <KeyFragment ref="variable_name" /> <KeyFragment>literal_string</KeyFragment> </CacheKey>
デフォルト: |
なし |
要否: |
必須 |
型: |
なし |
<CacheKey>
はキャッシュに保存される各データの名前を構成します。多くの場合、キーは、エンティティのヘッダーまたはクエリ パラメータに含まれる値を使用して設定されます。その場合、この要素の ref 属性で、キー値を格納する変数を指定します。
実行時に、<KeyFragment>
の値には <Scope>
要素の値または <Prefix>
の値が取り込まれます。たとえば、次の場合、キャッシュキーは UserToken__apiAccessToken__
<value_of_client_id> になります。
<CacheKey> <Prefix>UserToken</Prefix> <KeyFragment>apiAccessToken</KeyFragment> <KeyFragment ref="request.queryparam.client_id" /> </CacheKey>
<CacheKey>
要素は、<Prefix>
と <Scope>
を組み合わせて使用します。詳細については、キャッシュキーの使用をご覧ください。
<CacheLookupTimeoutInSeconds> 要素
キャッシュ ルックアップが失敗してから、キャッシュミスとみなすまでの秒数を指定します。キャッシュミスとみなされると、キャッシュミス パスに沿ってフローが再開されます。
<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>
デフォルト: |
30 |
要否: |
省略可 |
型: |
整数 |
<CacheResource> 要素
メッセージを保存するキャッシュを指定します。組み込み共有キャッシュを使用する場合は、この要素を省略します。キャッシュに含まれるエントリを管理者によってクリアできるようにする場合は、名前で CacheResource
を指定する必要があります。詳細については、キャッシュ API をご覧ください。
<CacheResource>cache_to_use</CacheResource>
デフォルト: |
なし |
要否: |
省略可 |
型: |
文字列 |
<CacheKey>/<KeyFragment> 要素
キャッシュキーに含める値を指定する要素です。この値を使用して、リクエストをキャッシュに保存されたレスポンスと照合するための名前空間が作成されます。
<KeyFragment ref="variable_name"/> <KeyFragment>literal_string</KeyFragment>
デフォルト: |
なし |
要否: |
省略可 |
型: |
なし |
この要素には、キー(ユーザーが指定する静的な名前)または値(変数を参照して動的に設定されるエントリ)を指定できます。指定されたすべてのフラグメント(および接頭辞)が連結されてキャッシュキーが作成されます。
<KeyFragment>apiAccessToken</KeyFragment> <KeyFragment ref="request.queryparam.client_id" />
<KeyFragment>
要素は、<Prefix>
と <Scope>
を組み合わせて使用します。詳細については、キャッシュキーの使用をご覧ください。
属性
属性 | 型 | デフォルト | 必須 | 説明 |
---|---|---|---|---|
ref | 文字列 | いいえ |
値を取得する変数。この要素にリテラル値が含まれている場合は、使用できません。 |
<CacheKey>/<Prefix> 要素
キャッシュキーの接頭辞として使用する値を指定する要素です。
<Prefix>prefix_string</Prefix>
デフォルト: |
なし |
要否: |
省略可 |
型: |
文字列 |
<Scope>
列挙値ではなく独自の値を指定するには、<Scope>
の代わりにこの要素の値を使用します。この要素が定義されている場合、<Prefix>
によって、キャッシュに書き込まれたエントリの先頭にキャッシュキー値が付加されます。<Prefix>
要素の値は、<Scope>
要素の値をオーバーライドします。
<Prefix>
要素は、<CacheKey>
と <Scope>
を組み合わせて使用します。詳細については、キャッシュキーの使用をご覧ください。
<ExcludeErrorResponse> 要素
このポリシーでは、任意のステータス コードが設定された HTTP レスポンスをキャッシュに保存できます。つまり、2xx ステータス コードと 3xx ステータス コードを含む、成功レスポンスとエラー レスポンスの両方がキャッシュに保存されます。
エラー レスポンスを除外するには、この要素を true
(デフォルト)に設定します。HTTP エラー ステータス コードを含むターゲット レスポンスをキャッシュから除外しない場合は、false
に設定します。
この要素に役立つレスポンス キャッシュ パターンについては、アンチパターンの概要をご覧ください。
<ExcludeErrorResponse>true</ExcludeErrorResponse>
デフォルト: |
true |
要否: |
省略可 |
型: |
ブール値 |
<ExpirySettings> 要素
キャッシュ エントリの有効期限を指定する要素です。この要素が存在する場合、<TimeoutInSeconds>
が <TimeOfDay>
と <ExpiryDate>
の両方をオーバーライドします。
<ExpirySettings> <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds> <ExpiryDate ref="date_variable">expiration_date</ExpiryDate> </ExpirySettings>
デフォルト: |
なし |
要否: |
必須 |
型: |
なし |
<ExpirySettings> / <ExpiryDate> 要素
キャッシュ エントリの有効期限の日付を指定する要素です。mm-dd-yyyy
の形式を使用します。この要素が存在する場合、この要素の兄弟 <TimeoutInSeconds>
が <ExpiryDate>
をオーバーライドします。
<ExpirySettings> <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate> </ExpirySettings>
デフォルト: |
なし |
要否: |
省略可 |
型: |
文字列 |
属性
<ExpiryDate ref="" />
属性 | 説明 | デフォルト | 要否 | 型 |
---|---|---|---|---|
ref |
値を取得する変数。この要素にリテラル値が含まれている場合は、使用できません。 |
なし | 省略可 | 文字列 |
<ExpirySettings>/<TimeOfDay> 要素
キャッシュ エントリの有効期限が切れる時刻を指定する要素です。hh:mm:ss
の形式を使用します。この要素が存在する場合、この要素の兄弟 <TimeoutInSeconds>
が <TimeOfDay>
をオーバーライドします。
時刻は HH:mm:ss の形式で入力します。HH は 24 時間制の時間を表します。たとえば、午後 2 時 30 分の場合は 14:30:00 を指定します。
時刻のデフォルトのロケールとタイムゾーンは、コードが動作している場所によって異なります(これはポリシーの構成時には把握できません)。
<ExpirySettings> <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> </ExpirySettings>
デフォルト: |
なし |
要否: |
省略可 |
型: |
文字列 |
属性
属性 | 説明 | デフォルト | 要否 | 型 |
---|---|---|---|---|
ref | 有効期限の時刻の値を格納する変数。 | なし | 省略可 | 文字列 |
<ExpirySettings>/<TimeoutInSec> 要素
キャッシュ エントリが期限切れになるまでの秒数。
<ExpirySettings>/<TimeoutInSeconds> 要素
キャッシュ エントリが期限切れになるまでの秒数。この要素が存在する場合、この要素により兄弟(<TimeOfDay>
と <ExpiryDate>
)がオーバーライドされます。
<ExpirySettings> <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds> </ExpirySettings>
デフォルト: |
なし |
要否: |
省略可 |
型: |
文字列 |
属性
属性 | 説明 | デフォルト | 要否 | 型 |
---|---|---|---|---|
ref | タイムアウト値を格納する変数。 |
なし
|
省略可 | 文字列 |
<Scope> 要素
<Prefix>
要素が <CacheKey>
要素で指定されていない場合に、キャッシュキーの接頭辞を作成するために使用される列挙値です。
<Scope>scope_enumeration</Scope>
デフォルト: |
「Exclusive」 |
要否: |
省略可 |
型: |
文字列 |
<Scope>
の設定は、<Scope>
の値に応じて接頭辞が付加されるキャッシュキーを決定します。たとえば、スコープが Exclusive
に設定されている場合、キャッシュキーの形式は orgName__envName__apiProxyName__proxy|TargetName__ [serializedCacheKey] になります。
<Prefix>
要素が <CacheKey>
に含まれている場合、この要素の値が <Scope>
要素の値を置き換えます。有効な値には、以下の列挙値が含まれます。
<Scope>
要素は、<CacheKey>
と <Prefix>
を組み合わせて使用します。詳細については、キャッシュキーの使用をご覧ください。
使用できる値
スコープ値 | 説明 |
---|---|
Global |
キャッシュキーが、環境にデプロイされているすべての API プロキシで共有されます。キャッシュキーは、orgName __ envName __ の形式で値の先頭に付加されます。
|
Application |
API プロキシ名が接頭辞として使用されます。 キャッシュキーは、orgName__envName__apiProxyName の形式で値の先頭に付加されます。 |
Proxy |
ProxyEndpoint 構成が接頭辞として使用されます。 キャッシュキーは、orgName__envName__apiProxyName__proxyEndpointName の形式で値の先頭に付加されます。 |
Target |
TargetEndpoint 構成が接頭辞として使用されます。 キャッシュキーは、orgName__envName__apiProxyName__targetEndpointName の形式で値の先頭に付加されます。 |
Exclusive |
デフォルト。これが最も特定的なスコープであるため、任意のキャッシュ内で名前空間が競合するリスクが最小限になります。 接頭辞は次のいずれかの形式をとります。
キャッシュキーは、orgName__envName__apiProxyName__proxyNameITargetName の形式で値の先頭に付加されます。 たとえば、完全な文字列は次のようになります。 apifactory__test__weatherapi__default__apiAccessToken |
<SkipCacheLookup> 要素
ランタイム時に true と評価されると、キャッシュ ルックアップをスキップしてキャッシュを更新する指定する式を定義します。SkipCacheLookup
の使用方法については、ResponseCache ポリシーの使用の動画もご覧ください。
<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>
デフォルト: |
なし |
要否: |
省略可 |
型: |
文字列 |
次の例では、受信ヘッダーで bypass-cache 変数が true に設定されている場合、キャッシュ ルックアップがスキップされて、キャッシュが更新されます。
<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
<SkipCachePopulation> 要素
ランタイム時に true と評価されると、キャッシュへの書き込みをスキップする式を定義します。SkipCachePopulation
の使用方法については、こちらの動画もご覧ください。
<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>
デフォルト: |
なし |
要否: |
省略可 |
型: |
文字列 |
次の例では、レスポンスのステータス コードが 400 以上の場合、キャッシュへの書き込みがスキップされます。
<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>
<UseAcceptHeader> 要素
true
に設定すると、レスポンス キャッシュ エントリのキャッシュキーにレスポンスの Accept ヘッダーの値を付加します。
Apigee は、キャッシュキーの計算時に Accept
、Accept-Encoding
、Accept-Language
、Accept-Charset
リクエスト ヘッダーを使用します。このアプローチにより、クライアントが要求していないメディアタイプを取得できなくなります。
たとえば、同じ URL から 2 つのリクエストを受信したとします。最初のリクエストでは gzip を受け入れ、2 番目のリクエストでは gzip を受け入れません。最初のリクエストがキャッシュに保存されると、そのキャッシュに保存されたエントリは(おそらく)gzip 形式のレスポンスになります。2 番目のリクエストは、キャッシュに保存された値を読み取り、gzip を読み取ることができないクライアントに gzip エントリされたエントリを返します。
詳細については、キャッシュキーの構成をご覧ください。
<UseAcceptHeader>false</UseAcceptHeader>
デフォルト: |
false |
プレゼンス: |
省略可 |
型: |
ブール値 |
<UseResponseCacheHeaders> 要素
キャッシュ内のレスポンスの「有効期間」(TTL)を設定する際に、HTTP レスポンス ヘッダーを含めるには、true
に設定します。true の場合、Apigee は、有効期間を設定するときに、次のレスポンス ヘッダーの値を考慮し、さらに <ExpirySettings>
によって設定された値を比較します。
Cache-Control s-maxage
Cache-Control max-age
Expires
詳細については、キャッシュ エントリの有効期限の設定をご覧ください。
<UseResponseCacheHeaders>false</UseResponseCacheHeaders>
デフォルト: |
false |
プレゼンス: |
省略可 |
型: |
ブール値 |
使用上の注意
キャッシュに保存される各オブジェクトの最大サイズは 256 KB です(Apigee でキャッシュがどのように処理されるかについては、キャッシュの仕組みをご覧ください)。
ResponseCache ポリシーを構成することで、Apigee にキャッシュ エントリの有効期限とキャッシュキーの設定に HTTP レスポンス ヘッダーを含めることができます。このセクションでは、ポリシーを使用してヘッダーでキャッシュの有効期限とキャッシュキーを管理する方法について説明します。
Apigee で ResponseCache ポリシーを使用してレスポンス ヘッダーを処理する方法については、HTTP レスポンス ヘッダーのサポートをご覧ください。
キャッシュ エントリの有効期限の設定
PopulateCache ポリシーの場合と同じく、<ExpirySettings>
要素を使用してレスポンス キャッシュ エントリの有効期限(有効期間)を設定できます。ResponseCache ポリシーでは、レスポンス ヘッダーが存在する場合でも Apigee によってレスポンス ヘッダーを考慮できます。
レスポンス ヘッダーを使用するには、<UseResponseCacheHeaders>
要素の値を true に設定します。この設定を行うと、Apigee はレスポンス ヘッダーを考慮し、それらを <ExpirySettings>
で設定された値と比較してから、2 つの間の最小値を使用します。レスポンス ヘッダーを考慮する際に、以下に示されている値が Apigee で選択します。
たとえば、レスポンスが次の値でキャッシュに保存されているとします。
Cache-Control s-maxage
の値はありません。Cache-Control max-age
の値は 300 です。Expires
の日付は 3 日後に設定されています。<ExpirySettings>
TimeoutInSeconds
の値は 600 です。
この場合、TTL には Cache-Control
max-age
の値が使用されます。この値のほうが <ExpirySettings>
の値より小さく、max-age
に優先される Cache-Control s-maxage
の値がないためです。
キャッシュキーの構成
PopulateCache ポリシーなどの汎用のキャッシュ ポリシーの場合と同じく、ResponseCache でも <CacheKey>
要素と <Scope>
要素を使用してキャッシュ エントリのキャッシュキーの作成を構成できます。ResponseCache では、レスポンス Accept ヘッダーをキー値に追加することで、キャッシュキーをさらに活用できます。
キャッシュキーの構成に関する一般的な情報については、キャッシュキーの使用をご覧ください。Accept ヘッダーの使用方法については、<UseAcceptHeader>
をご覧ください。
キャッシュの暗号化について
Apigee と Apigee ハイブリッド(バージョン 1.4 以降): キャッシュと KVM データは常に暗号化されます。
フロー変数
ResponseCache ポリシーの実行時は、次の定義済みフロー変数に値が取り込まれます。フロー変数の詳細については、フロー変数リファレンスをご覧ください。
変数 | 型 | 権限 | 説明 |
---|---|---|---|
responsecache.{policy_name}.cachename |
文字列 | 読み取り専用 | ポリシーで使用されたキャッシュを返します。 |
responsecache.{policy_name}.cachekey |
文字列 | 読み取り専用 | 使用されたキーを返します |
responsecache.{policy_name}.cachehit |
ブール値 | 読み取り専用 | ポリシーの実行が成功した場合は true |
responsecache.{policy_name}.invalidentry |
ブール値 | 読み取り専用 | キャッシュ エントリが有効でない場合は true |
エラーコード
This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.
Error code prefix
N/A
Runtime errors
This policy does not throw any runtime errors.
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause | Fix |
---|---|---|
InvalidTimeout |
If the
<CacheLookupTimeoutInSeconds> element of the ResponseCache policy is set to a negative number,
then the deployment of the API proxy fails. |
build |
InvalidCacheResourceReference |
This error occurs if the <CacheResource> element in a ResponseCache policy is set to a
name that does not exist in the environment where the API proxy is being deployed. |
build |
ResponseCacheStepAttachmentNotAllowedReq |
This error occurs if the same ResponseCache policy is attached to multiple request
paths within any flows of an API proxy. |
build |
ResponseCacheStepAttachmentNotAllowedResp |
This error occurs if the same ResponseCache policy is attached to multiple response
paths within any flows of an API proxy. |
build |
InvalidMessagePatternForErrorCode |
This error occurs if either the <SkipCacheLookup> or the <SkipCachePopulation>
element in a ResponseCache policy contains an invalid condition. |
build |
CacheNotFound |
This error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component. | build |
Fault variables
N/A
Example error response
N/A
スキーマ
各ポリシータイプは XML スキーマ(.xsd
)によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。