ResponseCache ポリシー

このページは ApigeeApigee ハイブリッドに適用されます。

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

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

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

なし 必須
continueOnError

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

ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連項目:

false 省略可
enabled

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

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

true 省略可
async

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

false 非推奨

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<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 を指定する必要があります。詳細については、キャッシュ 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 のレスポンスもデフォルトでキャッシュに保存されます。

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

この要素に役立つレスポンス キャッシュ パターンについては、アンチパターンの概要をご覧ください。

<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 タイムアウト値を格納する変数。
なし
省略可 文字列

<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 の使用方法については、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 は、キャッシュキーの計算時に AcceptAccept-EncodingAccept-LanguageAccept-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 で選択します。

UseResponseCacheHeaders を true に設定した場合の動作を示す図。

たとえば、レスポンスが次の値でキャッシュに保存されているとします。

  • 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

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに設定されるエラー メッセージとフロー変数について説明します。これは、プロキシの障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

エラーコードの接頭辞

なし

ランタイム エラー

このポリシーはランタイム エラーをスローしません。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名 原因 修正
InvalidTimeout ResponseCache ポリシーの <CacheLookupTimeoutInSeconds> 要素が負の数に設定されている場合、API プロキシのデプロイが失敗します。
InvalidCacheResourceReference このエラーは、API プロキシがデプロイされている環境に存在しない名前が ResponseCache ポリシーの <CacheResource> 要素に設定されている場合に発生します。
ResponseCacheStepAttachmentNotAllowedReq このエラーは、同じ ResponseCache ポリシーが API プロキシの任意のフロー内の複数のリクエストパスに接続されている場合に発生します。
ResponseCacheStepAttachmentNotAllowedResp このエラーは、同じ ResponseCache ポリシーが API プロキシの任意のフロー内の複数のレスポンスパスに接続されている場合に発生します。
InvalidMessagePatternForErrorCode このエラーは、ResponseCache ポリシーの <SkipCacheLookup> 要素と <SkipCachePopulation> 要素のいずれかに無効な条件が含まれている場合に発生します。
CacheNotFound このエラーは、エラー メッセージに記述されているキャッシュが、特定の Message Processor コンポーネント上に作成されていない場合に発生します。

障害変数

なし

エラー レスポンスの例

なし

スキーマ

各ポリシータイプは XML スキーマ(.xsd)によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。