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>
            <TimeoutInSec>600</TimeoutInSec>
        </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>
            <TimeoutInSec>600</TimeoutInSec>
        </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/>
            <TimeoutInSec ref="flow.variable.here">300</TimeoutInSec>
        </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>
    

デフォルト:

なし

必須?:

省略可

型:

文字列

キャッシュを構成する方法について詳しくは、環境キャッシュの作成と編集をご覧ください。

<ExcludeErrorResponse> 要素

現在、このポリシーはデフォルトで、考えられるあらゆるステータス コードが設定された HTTP レスポンスをキャッシュに保存します。つまり、成功レスポンスとエラー レスポンスの両方がキャッシュに保存されるということです。たとえば、ステータス コードが 2xx のレスポンスも 3xx のレスポンスもデフォルトでキャッシュに保存されます。

HTTP エラーのステータス コードを伴うターゲット レスポンスがキャッシュに保存されないようにするには、この要素を true に設定します。この要素が true に設定されている場合は、ステータス コードが 200~205 となっているレスポンスだけがキャッシュに保存されます。Edge が「成功」コードとしてみなすのは、これらの HTTP ステータス コードのみです。この関連付けを変更することはできません。

この要素が役立つ Response Cache ポリシーのパターンについては、こちらのコミュニティの投稿をご覧ください。

注: 今後のリリース(未定)で、この要素のデフォルト設定は true に変更される予定です。詳しくは、Apigee リリースノートをご覧ください。

    <ExcludeErrorResponse>true</ExcludeErrorResponse>
    

デフォルト:

false

必須?:

省略可

型:

ブール値

<ExpirySettings> / <ExpiryDate> 要素

キャッシュ エントリの有効期限の日付を指定する要素です。mm-dd-yyyy の形式を使用します。この要素が存在する場合、この要素の兄弟 <TimeoutInSec><ExpiryDate> をオーバーライドします。

    <ExpirySettings>
        <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
    </ExpirySettings>
    

デフォルト:

なし

必須?:

省略可

型:

String

属性

    <ExpiryDate ref="" />
    
属性 説明 デフォルト 要否
ref

値の取得元とする変数。この要素にリテラル値が含まれている場合は、使用できません。

なし 省略可 文字列

<ExpirySettings> 要素

キャッシュ エントリの有効期限を指定する要素です。この要素が存在する場合、<TimeoutInSec><TimeOfDay><ExpiryDate> の両方をオーバーライドします。

    <ExpirySettings>
      <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
      <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
      <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
    </ExpirySettings>
    

デフォルト:

なし

必須?:

必須

型:

なし

<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> とあわせて使用します。詳しくは、キャッシュキーの使用をご覧ください。

<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>
    

<ExpirySettings> / <TimeOfDay> 要素

キャッシュ エントリの有効期限が切れる時刻を指定する要素です。hh:mm:ss の形式を使用します。この要素が存在する場合、この要素の兄弟 <TimeoutInSec><TimeOfDay> をオーバーライドします。

時刻は HH:mm:ss の形式で入力します。HH は 24 時間制の時間を表します。たとえば、午後 2 時 30 分の場合は 14:30:00 と入力します。

時刻のデフォルトのロケールとタイムゾーンは、コードが実行される場所によって異なります(ポリシーの構成時には確定していません)。ロケールの構成については、環境キャッシュの作成と編集をご覧ください。

    <ExpirySettings>
        <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
    </ExpirySettings>
    

デフォルト:

要否:

省略可

型:

String

属性

属性 説明 デフォルト 要否
ref 有効期限の時刻の値を格納する変数。 なし 省略可 文字列

<ExpirySettings> / <TimeoutInSec> 要素

キャッシュ エントリが期限切れになるまでの秒数を指定する要素です。この要素が存在する場合、この要素の兄弟である <TimeOfDay><ExpiryDate> がオーバーライドされます。

    <ExpirySettings>
        <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
    </ExpirySettings>
    

デフォルト:

なし

必須?:

省略可

型:

String

属性

属性 説明 デフォルト 要否
ref タイムアウト値を格納する変数。
なし
省略可 文字列

<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 がキャッシュを処理する方法について詳しくは、Cache の仕組みをご覧ください)。

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> TimeOutInSec の値は 600 です。

この場合、TTL には Cache-Control max-age の値が使用されます。この値のほうが <ExpirySettings> の値より小さいため、そして(max-age に優先される)Cache-Control s-maxage の値がないためです。

キャッシュキーの構成

Populate Cache ポリシーなどの汎用のキャッシュ ポリシーの場合と同じく、ResponseCache でも <CacheKey> 要素と <Scope> 要素を使用してキャッシュ エントリのキャッシュキーの作成を構成できます。ResponseCache の場合、レスポンスの Accept ヘッダーをキー値の先頭に付加することで、より意味のあるキャッシュキーにすることもできます。

キャッシュキーの構成方法の概要については、キャッシュキーの使用をご覧ください。Accept ヘッダーの使用方法については、<UseAcceptHeader> をご覧ください。

フロー変数

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 に参照用のポリシー スキーマが用意されています。