キャッシュキーの使用

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

Apigee Edge のドキュメントを表示する。

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

Apigee は、構成要素（<Scope>、<CacheKey> / <Prefix>、<CacheKey> / <KeyFragment>）の値を使用して、キャッシュキーの値を構成します。これは、キャッシュ内の値に関連付けられた識別子です。キャッシュキーの構成は、すべてのキャッシュポリシーで同じように機能します。

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

キャッシュ構成要素	説明
`<Scope>` または `<CacheKey>` / `<Prefix>`	`<Scope>` または `<CacheKey>` `<Prefix>` 要素を使用して、最終的なキャッシュキーに適用する接頭辞を構成します。`<Scope>` は、事前定義された値のリストを列挙します。`<CacheKey>` `<Prefix>` 要素は、`<Scope>` を独自に選択した固定値でオーバーライドします。
`<CacheKey>` / `<KeyFragment>`	1 つ以上の `<CacheKey>` `<KeyFragment>` 要素を使用して、キャッシュエントリの一意の識別子を指定します。KeyFragment の値は、リテラルにすることも、変数から設定することもできます。

Apigee は、2 つの部分（接頭辞と複合フラグメント部分）から成るキャッシュキーを 2 個のアンダースコアで区切って構成します。

PREFIX_PART__FRAGMENT_PART

接頭辞は、<Scope> 要素、または <CacheKey> <Prefix> 要素（存在する場合）によって決まります。フラグメントの部分は、各 <KeyFragment> 要素の値で構成され、2 個のアンダースコアで結合されます。

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

<CacheKey> の使用

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

<CacheKey> 要素には、オプションの <Prefix> 要素を 1 つと、<KeyFragment> 要素を 1 つ以上含めることができます。Apigee は実行時に、各部分から判別した値を 2 個のアンダースコアで連結して、キャッシュキーを作成します。

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

<CacheKey>
    <Prefix>myprefix</Prefix>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

次に示すように、<KeyFragment> 要素内の変数を参照することで、動的に構成されるキャッシュキーを使用するように Apigee を構成できます。

<KeyFragment ref="variable_name"/>

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

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

次のような構成について考えてみましょう。

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

request.header.Content-Type 変数の値が application/json の場合、キャッシュキーは system1__apiAccessToken__application/json__bar になります。

ref 属性では、プラットフォーム定義の変数またはカスタム変数を使用できます。

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

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>

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

prefix_part__value1__value2

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

<Scope> と <Prefix> の使用

<Scope> 要素と <CacheKey> / <Prefix> 要素を使用すると、キャッシュに保存された値を名前空間に整理できます。Apigee は、これらの値から派生した値をキャッシュキーの先頭に追加します。キャッシュキーでスコープまたは接頭辞を使用するメリットは、InvalidateCache ポリシーを 1 回呼び出すだけで、1 つの接頭辞を共有する値をすべて無効にできる点です。

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

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

mycompany__prod__[FRAGMENT_PART]

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

orgName__envName__apiProxyName__deployedRevisionNumber__nameof(proxyEndpoint|targetEndpoint)__[serializedCacheKey]

次の例では、「weatherapi」という名前のプロキシの 16 番目のリビジョンが「mycompany」という組織と「prod」という名前の環境にデプロイされ、proxyEndpoint の名前が「default」で、キャッシュポリシーが proxyEndpoint のフローに接続されていると仮定しています。

構成結果

構成	結果
<Scope>Global</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	`mycompany__prod__hello__world`.
<Scope>Exclusive</Scope> <CacheKey> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	`mycompany__prod__weatherapi__16__default__hello__world`
<Scope>Exclusive</Scope> <CacheKey> <Prefix>system1</Prefix> <KeyFragment>hello</KeyFragment> <KeyFragment>world</KeyFragment> <CacheKey>	`system1__hello__world`

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

mycompany__prod__hello__world.

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

mycompany__prod__weatherapi__16__default__hello__world

<Scope>Exclusive</Scope>
<CacheKey>
    <Prefix>system1</Prefix>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

system1__hello__world

キャッシュキーの使用

<CacheKey> の使用

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

<Scope> と <Prefix> の使用

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