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

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails. See also:

false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional
Type String

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

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

Application

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

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

Proxy

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

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

Target

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

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

Exclusive

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

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

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

キャッシュキーは、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 は、キャッシュキーの計算時に 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 から入手できます。