ResponseCache ポリシー

バックエンドからのデータをキャッシュに保存して、リソースに対するリクエスト数を削減します。このポリシーを使用すると、アプリが以前と同じ 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

ポリシーの内部名。name 属性の値には、文字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。255 文字を超える値を指定することはできません。

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

<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 __ の形式で値の先頭に付加されます。

<KeyFragment> apiAccessToken と <Global> スコープを設定した <CacheKey> エントリを定義すると、各エントリは、シリアル化されたアクセス トークン値が続く orgName__envName__apiAccessToken として保存されます。たとえば、「apifactory」という組織の「test」という環境にデプロイされた API プロキシの場合、アクセス トークンはキャッシュキー apifactory__test__apiAccessToken で保存されます。

Application

API プロキシ名が接頭辞として使用されます。

キャッシュキーは、orgName__envName__apiProxyName の形式で値の先頭に付加されます。

Proxy

ProxyEndpoint 構成が接頭辞として使用されます。

キャッシュキーは、orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName の形式で値の先頭に追加されます。

Target

TargetEndpoint 構成が接頭辞として使用されます。

キャッシュキーは、orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName の形式で値の先頭に追加されます。

Exclusive

デフォルト。これが最も特定的なスコープであるため、任意のキャッシュ内で名前空間が競合するリスクが最小限になります。

接頭辞は次のいずれかの形式をとります。

  • ポリシーが ProxyEndpoint フローに接続されている場合、接頭辞は ApiProxyName_ProxyEndpointName の形式になります。
  • ポリシーが TargetEndpoint に接続されている場合、接頭辞は ApiProxyName_TargetName の形式になります。

キャッシュキーは、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 では、キャッシュキーを計算する際に AcceptAccept-EncodingAccept-LanguageAccept-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: キャッシュは、PCIHIPAA が有効にされた組織でのみ暗号化されます。これらの組織での暗号化は、組織のプロビジョニング時に構成されます。

フロー変数

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.
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.
ResponseCacheStepAttachmentNotAllowedReq This error occurs if the same ResponseCache policy is attached to multiple request paths within any flows of an API proxy.
ResponseCacheStepAttachmentNotAllowedResp This error occurs if the same ResponseCache policy is attached to multiple response paths within any flows of an API proxy.
InvalidMessagePatternForErrorCode This error occurs if either the <SkipCacheLookup> or the <SkipCachePopulation> element in a ResponseCache policy contains an invalid condition.
CacheNotFound This error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component.

Fault variables

N/A

Example error response

N/A

スキーマ

各ポリシータイプは XML スキーマ(.xsd)で定義されています。GitHub に参照用のポリシー スキーマが用意されています。