キャッシュキーの使用

キャッシュ ポリシーを使用する際は、キャッシュに保存される値のキーが一意になるようにキャッシュキーを構成します。キャッシュに保存したデータと同じデータをキャッシュから取得するには、キャッシュキーと他の構成可能な値が信頼できる手段になります。キャッシュキーは、Populate Cache ポリシー、LookupCache ポリシー、InvalidateCache ポリシー、Response Cache ポリシーで使用します。

構成要素の値（<CacheKey> / <KeyFragment>、<Scope>、<Prefix>）が連結され、キャッシュに格納された値に関連付けられる識別子が作成されます。ID の値を取得する場合も、この同じ構成を使用します。

キャッシュキーを作成するには、キャッシュ ポリシーの次の構成要素を使用できます。

これらの値は次の形式で連結され、<Scope> または <Prefix> の値は KeyFragment の値とは 2 つのアンダースコアで区切られます。KeyFragment の複数の値も 2 つのアンダースコアで区切られます。

scope | prefix__keyfragment[__keyfragment]

Response Cache ポリシーを使用すると、必要に応じてこのキャッシュキーをレスポンスの Accept ヘッダーの値に追加できます。

<CacheKey> の使用

<CacheKey> 要素は、Edge が作成するキャッシュ エントリごとに一意の識別子（キー）を作成する方法を構成します。Edge はキャッシュに保存されている値を取得する際に、キャッシュキーを使用して正しい値を見つけます。ResponseCache ポリシーでは、値をキャッシュに保存する際とキャッシュから値を取得する際に使用するキーを 1 つの構成で定義します。PopulateCache ポリシーと LookupCache ポリシーでは、キャッシュから取得した値がそこに配置された値と一致するように、各ポリシーに同じ <CacheKey> 要素を指定します。

<CacheKey> 要素には複数の <KeyFragment> 要素を含めることが可能です。ランタイム時に、<KeyFragment> 要素によって指定された値は 2 つのアンダースコアで連結され、キャッシュキーの一部を構成します。

たとえば、次の構成では、キャッシュキーで使用する hello__world の値が作成されます。

<CacheKey>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

次のように、<KeyFragment> 要素の変数を参照することで、キャッシュキーで変数値を使用することもできます。

<KeyFragment ref="variable_name"/>

たとえば、キャッシュキーの値に Content-Type のリクエスト メッセージを組み込むには、次のようにします。

<KeyFragment ref="request.header.Content-Type"/>

次の構成では、request.header.Content-Type 変数の値は application/json です。

<CacheKey>
  <KeyFragment>apiAccessToken</KeyFragment>
  <KeyFragment ref="request.header.Content-Type" />
  <KeyFragment>bar</KeyFragment>
</CacheKey>

この結果、apiAccessToken__application/json__bar で終わるキャッシュキーが返されます。

使用できる変数のリストについては、変数リファレンスをご覧ください。

クエリ パラメータから導出されるキャッシュキー

request.queryparam.<queryparam_name> や request.querystring などの変数を使用してキャッシュキーを構成し、キーにリクエストのクエリ文字列が含まれるようにできます。たとえば、次の URL には param1 と param2 が含まれています。この 2 つのクエリ パラメータをキャッシュキーで使用できます。

http://myaccount.apigee.net/mydata?param1=value1&param2=value2

<CacheKey> 要素には、次のような構成でこれらの値を組み込むことができます。

<CacheKey>
    <KeyFragment ref="request.queryparam.param1" />
    <KeyFragment ref="request.queryparam.param2" />
<CacheKey>

ランタイム時に、次のように連結されたクエリ パラメータの値がキャッシュキーに組み込まれます。

other_key_parts__value1__value2

変数を使用してパラメータから値を挿入する場合、値は <KeyFragment> 要素の順序で提案された順序で連結されます。また、Edge では、<KeyFragment> 要素で具体的に参照する値のみが使用されます。リクエストのクエリ パラメータ リストが異なる場合、その違いはキャッシュキーで考慮されません。

代わりの手法となるのは、request.querystring 変数を使用することです。この場合、パラメータの文字列全体が文字通りにキャッシュキーに挿入されます。この手法ではすべてのパラメータが考慮されますが、リクエストで使用されていたパラメータの順序が次のリクエストで異なっている場合は、キーも異なります。つまり、param1=value1&param2=value2 と param2=value2&param1=value1 は同じキャッシュキー値になりません。

使用できる変数のリストについては、変数リファレンスをご覧ください。

<Scope> と <Prefix> の使用

<Scope> 要素と <Prefix> 要素を使用すると、キーに名前空間の接頭辞を追加できます。これらの要素が表す値が、キャッシュキーの先頭に付加されます。

デフォルトでは <Scope> 要素が使用されます。この要素が列挙する値は広いスコープから限定的なスコープまで指定しますが、場合デフォルトでは最も限定的なスコープが使用されます。このデフォルト値は、別の値を指定するか、<Prefix> 要素の値を指定しない限り使用されます。<Prefix> 要素を使用して <Scope> 値をオーバーライドし、名前空間のカスタム値を指定できます。

たとえば、<Scope> 値の「Global」（最も広い範囲）は組織名と環境名を表します。「mycompany」という名前の組織の「prod」という名前の環境にプロキシがデプロイされているとすると、次の値がキャッシュキーの先頭に付加されます。

上記に定義された Global スコープをキャッシュキーで使用する場合は、次のようになります。

<Scope>Global</Scope>
<CacheKey>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

LookupCache ポリシーで説明されているように、スコープは、Global から Exclusive に限定性を高めるように構成できます。Exclusive は最も限定的なスコープであるため、特定のキャッシュ内で名前空間が競合するリスクが最小限になります。Exclusive スコープを使用すると、各キャッシュ エントリの先頭に次の形式の接頭辞が付加されます。

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__[serializedCacheKey]

たとえば、<Scope> の値として Exclusive を使用すると、次のようなキャッシュキーが作成されます。

apifactory__test__weatherapi__16__default__apiAccessToken