バックエンドからのデータをキャッシュに保存して、リソースに対するリクエスト数を削減します。このポリシーを使用すると、アプリが以前と同じ URI にリクエストを送信した場合、そのリクエストをバックエンド サーバーに転送する代わりに、キャッシュに保存されているレスポンスをアプリに返すことができます。ResponseCache ポリシーによってレイテンシとネットワーク トラフィックを削減することで、API のパフォーマンスが向上します。
API で使用されるバックエンド データが定期的にしか更新されない場合、ResponseCache は非常に便利です。たとえば、10 分間隔で更新される気象レポートを公開する API があるとします。ResponseCache を使用して、更新のたびにキャッシュに保存されたレスポンスが返されるようにすれば、バックエンドに到達するリクエストの数を削減できます。これにより、ネットワーク ホップ数も削減されます。
汎用目的で短期間保存されるキャッシュの場合は、Populate Cache ポリシーの使用を検討してください。このポリシーは、Lookup Cache ポリシー(キャッシュ エントリの読み取りに関するポリシー)と Invalidate Cache ポリシー(エントリの無効化に関するポリシー)と組み合わせて使用します。
Response Cache ポリシーの概要を説明する動画をご覧ください。
例
10 分間のキャッシュ
この例では、キャッシュに保存されたレスポンスを 10 分間保持する方法を説明します。
次の URL にある API を使用しているとします。
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
ここでは、クエリ パラメータ w
をキャッシュキーとして使用しています。Apigee Edge はリクエストを受信するたびに、クエリ パラメータ 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 を名前で指定する必要があります。詳細については、キャッシュをご覧ください。
<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 のレスポンスもデフォルトでキャッシュに保存されます。
HTTP エラーのステータス コードを伴うターゲット レスポンスがキャッシュに保存されないようにするには、この要素を true
に設定します。この要素が true に設定されている場合は、ステータス コードが 200~205 となっているレスポンスだけがキャッシュに保存されます。Edge が「成功」コードとしてみなすのは、これらの HTTP ステータス コードのみです。この関連付けを変更することはできません。
この要素が役立つ Response Cache ポリシーのパターンについては、こちらのコミュニティの投稿をご覧ください。
注: 今後のリリース(未定)で、この要素のデフォルト設定は true に変更される予定です。詳しくは、Apigee リリースノートをご覧ください。
<ExcludeErrorResponse>true</ExcludeErrorResponse>
デフォルト: |
false |
要否: |
省略可 |
型: |
ブール値 |
<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 が duration_variable
から値を受け取らない場合に使用するデフォルトのタイムアウト値を指定します。
デフォルト: |
なし |
要否: |
省略可 |
型: |
文字列 |
属性
属性 | 説明 | デフォルト | 要否 | 型 |
---|---|---|---|---|
ref | タイムアウト値を格納する変数。 |
なし
|
省略可 | 文字列 |
<Scope> 要素
<Prefix>
要素が <CacheKey>
要素で指定されていない場合に、キャッシュキーの接頭辞を作成するために使用される列挙値です。
<Scope>scope_enumeration</Scope>
デフォルト: |
「Exclusive」 |
要否: |
省略可 |
型: |
文字列 |
<Scope>
の設定により、<Scope>
の値に応じて接頭辞が付加されるキャッシュキーが決まります。たとえば、スコープが Exclusive
に設定されている場合、キャッシュキーの形式は orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [serializedCacheKey] となります。
<Prefix>
要素が <CacheKey>
に含まれている場合、この要素の値が <Scope>
要素の値より優先されます。有効な値には、以下の列挙値が含まれます。
<Scope>
要素は <CacheKey>
や <Prefix>
と組み合わせて使用します。詳細については、キャッシュキーの使用をご覧ください。
有効な値
スコープ値 | 説明 |
---|---|
Global |
キャッシュキーが、環境にデプロイされているすべての API プロキシで共有されます。キャッシュキーは、orgName __ envName __ の形式で値の先頭に付加されます。
|
Application |
API プロキシ名が接頭辞として使用されます。 キャッシュキーは、orgName__envName__apiProxyName の形式で値の先頭に付加されます。 |
Proxy |
ProxyEndpoint 構成が接頭辞として使用されます。 キャッシュキーは、orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName の形式で値の先頭に追加されます。 |
Target |
TargetEndpoint 構成が接頭辞として使用されます。 キャッシュキーは、orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName の形式で値の先頭に追加されます。 |
Exclusive |
デフォルト。これが最も特定的なスコープであるため、任意のキャッシュ内で名前空間が競合するリスクが最小限になります。 接頭辞は次のいずれかの形式をとります。
キャッシュキーは、orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName の形式で値の先頭に追加されます。 たとえば、完全な文字列は次のようになります。 apifactory__test__weatherapi__16__default__apiAccessToken |
<SkipCacheLookup> 要素
条件式を定義する要素です。ランタイム時にこの条件が true に評価された場合、キャッシュ ルックアップがスキップされて、キャッシュが更新されます。SkipCacheLookup の使用方法については、こちらの動画もご覧ください。
<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> 要素
レスポンスのキャッシュ エントリのキャッシュキーの先頭に、レスポンスの Accept ヘッダーに含まれる値を付加する場合は、この要素を true
に設定します。
Edge では、キャッシュキーを計算する際に 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 に設定されている場合、Edge は有効期間を設定する際に、次のレスポンス ヘッダーを考慮し、それらの値を <ExpirySettings>
で設定されている値と比較します。
Cache-Control s-maxage
Cache-Control max-age
Expires
詳しくは、キャッシュ エントリの有効期限を設定するをご覧ください。
<UseResponseCacheHeaders>false</UseResponseCacheHeaders>
デフォルト: |
false |
要否: |
省略可 |
型: |
ブール値 |
使用上の注意
キャッシュに保存される各オブジェクトの最大サイズは 512 KB です(Edge がキャッシュを処理する方法については、キャッシュの仕組みをご覧ください)。
ResponseCache ポリシーを構成することで、Edge がキャッシュ エントリとキャッシュキーを設定する際に HTTP レスポンス ヘッダーを考慮するように設定できます。このセクションでは、ポリシーでヘッダーを使用してキャッシュの有効期限とキャッシュキーを管理する方法を説明します。
Edge が ResponseCache ポリシーでレスポンス ヘッダーを処理する方法については、HTTP レスポンス ヘッダーのサポートをご覧ください。
キャッシュ エントリの有効期限を設定する
Populate Cache ポリシーの場合と同じく、レスポンス キャッシュ エントリの有効期限(有効期間)は <ExpirySettings>
要素を使用して設定できます。ResponseCache ポリシーでは、Edge にレスポンス ヘッダー(存在する場合)を考慮させることもできます。
レスポンス ヘッダーを使用するには、<UseResponseCacheHeaders>
要素の値を true に設定します。この設定では、Edge がレスポンス ヘッダーを考慮し、それらの値を <ExpirySettings>
で設定されている値と比較して、小さいほうの値を使用します。レスポンス ヘッダーを考慮する際に、Edge は以下に説明するプロセスに従って使用可能な値を選択します。
たとえば、キャッシュに保存されたレスポンスに次の値が設定されているとします。
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
の値がないためです。
キャッシュキーの構成
Populate Cache ポリシーなどの汎用のキャッシュ ポリシーの場合と同じく、ResponseCache でも <CacheKey>
要素と <Scope>
要素を使用してキャッシュ エントリのキャッシュキーの作成を構成できます。ResponseCache の場合、レスポンスの Accept ヘッダーをキー値の先頭に付加することで、より意味のあるキャッシュキーにすることもできます。
キャッシュキーの構成に関する一般的な情報については、キャッシュキーの使用をご覧ください。Accept ヘッダーの使用方法については、<UseAcceptHeader>
をご覧ください。
キャッシュの暗号化について
Edge for Public Cloud: キャッシュは、PCI と HIPAA が有効にされた組織でのみ暗号化されます。これらの組織での暗号化は、組織のプロビジョニング時に構成されます。
フロー変数
ResponseCache ポリシーの実行時は、次の定義済みフロー変数に値が取り込まれます。フロー変数の詳細については、変数リファレンスをご覧ください。
変数 | 型 | 権限 | 説明 |
---|---|---|---|
responsecache.{policy_name}.cachename |
文字列 | 読み取り専用 | ポリシーで使用されたキャッシュを返します。 |
responsecache.{policy_name}.cachekey |
文字列 | 読み取り専用 | 使用されたキーを返します。 |
responsecache.{policy_name}.cachehit |
ブール値 | 読み取り専用 | ポリシーの実行が成功した場合は true |
responsecache.{policy_name}.invalidentry |
ブール値 | 読み取り専用 | キャッシュ エントリが有効でない場合は true |
エラーコード
このセクションでは、このポリシーがエラーをトリガーしたときに設定されるエラー メッセージとフロー変数について説明します。これは、プロキシの障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
エラーコードの接頭辞
なし
ランタイム エラー
このポリシーはランタイム エラーをスローしません。
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
エラー名 | 原因 | 解決方法 |
---|---|---|
InvalidTimeout |
ResponseCache ポリシーの <CacheLookupTimeoutInSeconds> 要素が負の数に設定されている場合、API プロキシのデプロイは失敗します。 |
build |
InvalidCacheResourceReference |
このエラーは、ResponseCache ポリシーの <CacheResource> 要素が、API プロキシのデプロイ先の環境には存在しない名前に設定される場合に発生します。 |
build |
ResponseCacheStepAttachmentNotAllowedReq |
このエラーは、同じ ResponseCache ポリシーが API プロキシの任意のフロー内の複数のリクエスト パスに接続されている場合に発生します。 | build |
ResponseCacheStepAttachmentNotAllowedResp |
このエラーは、同じ ResponseCache ポリシーが API プロキシの任意のフロー内の複数のレスポンス パスに接続されている場合に発生します。 | build |
InvalidMessagePatternForErrorCode |
このエラーは、ResponseCache ポリシーの <SkipCacheLookup> 要素または <SkipCachePopulation> 要素に無効な条件が含まれている場合に発生します。 |
build |
CacheNotFound |
このエラーは、エラー メッセージに記述されているキャッシュが、特定の Message Processor コンポーネント上に作成されていない場合に発生します。 | build |
障害変数
なし
エラー レスポンスの例
なし
スキーマ
各ポリシータイプは XML スキーマ(.xsd
)で定義されています。GitHub に参照用のポリシー スキーマが用意されています。