ResponseCache ポリシー

バックエンドからのデータをキャッシュに保存して、リソースに対するリクエスト数を削減します。このポリシーを使用すると、アプリが以前と同じ URI にリクエストを送信した場合、そのリクエストをバックエンド サーバーに転送する代わりに、キャッシュに保存されているレスポンスをアプリに返すことができます。ResponseCache ポリシーによってレイテンシとネットワーク トラフィックを削減することで、API のパフォーマンスが向上します。

API で使用されるバックエンド データが定期的にしか更新されない場合、ResponseCache は非常に便利です。たとえば、10 分間隔で更新される気象レポートを公開する API があるとします。ResponseCache を使用して、更新のたびにキャッシュに保存されたレスポンスが返されるようにすれば、バックエンドに到達するリクエストの数を削減できます。これにより、ネットワーク ホップ数も削減されます。

汎用目的で短期間保存されるキャッシュの場合は、Populate Cache ポリシーの使用を検討してください。このポリシーは、Lookup Cache ポリシー（キャッシュ エントリの読み取りに関するポリシー）と Invalidate Cache ポリシー（エントリの無効化に関するポリシー）と組み合わせて使用します。

例

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "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">

次の表に、すべてのポリシーの親要素に共通する属性を示します。

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

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

属性

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

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

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

属性

<ExpirySettings> / <TimeoutInSec> 要素

キャッシュ エントリが期限切れになるまでの秒数を指定する要素です。

<ExpirySettings> / <TimeoutInSeconds> 要素

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

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

注: ref が duration_variable から値を受け取らない場合に使用するデフォルトのタイムアウト値を指定します。

属性

<Scope> 要素

<Prefix> 要素が <CacheKey> 要素で指定されていない場合に、キャッシュキーの接頭辞を作成するために使用される列挙値です。

<Scope>scope_enumeration</Scope>

<Scope> の設定により、<Scope> の値に応じて接頭辞が付加されるキャッシュキーが決まります。たとえば、スコープが Exclusive に設定されている場合、キャッシュキーの形式は orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [serializedCacheKey] となります。

<Prefix> 要素が <CacheKey> に含まれている場合、この要素の値が <Scope> 要素の値より優先されます。有効な値には、以下の列挙値が含まれます。

<Scope> 要素は <CacheKey> や <Prefix> と組み合わせて使用します。詳細については、キャッシュキーの使用をご覧ください。

有効な値

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>

<UseResponseCacheHeaders> 要素

キャッシュ内のレスポンスの「有効期間」（TTL）が設定される際に、HTTP レスポンス ヘッダーが考慮されるようにするには、この要素を true に設定します。この要素が true に設定されている場合、Edge は有効期間を設定する際に、次のレスポンス ヘッダーを考慮し、それらの値を <ExpirySettings> で設定されている値と比較します。

• Cache-Control s-maxage
• Cache-Control max-age
• Expires

詳しくは、キャッシュ エントリの有効期限を設定するをご覧ください。

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

使用上の注意

キャッシュに保存される各オブジェクトの最大サイズは 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 ポリシーの実行時は、次の定義済みフロー変数に値が取り込まれます。フロー変数の詳細については、変数リファレンスをご覧ください。

エラーコード

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.

Fault variables

N/A

Example error response

N/A

スキーマ

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