キャッシュキーの使用

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

構成要素 <CacheKey> または <KeyFragment> と、<Scope><Prefix> の値が連結されて、キャッシュに保存する特定の値に関連付ける ID が作成されます。ID の値を取得する場合も、この同じ構成を使用します。

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

キャッシュ構成要素 説明
<CacheKey> / <KeyFragment> <CacheKey> <KeyFragment> 要素の組み合わせを使用して、キャッシュ エントリの一意の ID を指定します。KeyFragment の値は、リテラルにすることも、変数から設定することもできます。
<Scope> または <Prefix> <Scope> または <Prefix> 要素を使用して、キャッシュキーの名前要素を指定します。<Scope> には、事前定義された値をリストとして列挙します。<Prefix> 要素は、ユーザーが選択した値で <Scope> をオーバーライドします。

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

scope | prefix__keyfragment[__keyfragment]

Response Cache ポリシーでは、必要に応じてこのキャッシュキーの先頭にレスポンスの Accept ヘッダーに含まれる値を付加できます。

<CacheKey> の使用

<CacheKey> 要素は、Edge が作成するキャッシュ エントリごとに一意の ID(キー)を作成する方法を構成します。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=value2param2=value2&param1=value1 ではキャッシュキーの値が異なります。

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

<Scope> と <Prefix> の使用

<Scope> 要素と <Prefix> 要素は、名前空間の接頭辞でキーを増補する手段となります。これらの要素が表す値が、キャッシュキーの先頭に付加されます。

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

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

構成 結果
<Scope>Global</Scope> mycompany__prod__

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

構成 結果

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

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

    orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__[serializedCacheKey]
    

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

    apifactory__test__weatherapi__16__default__apiAccessToken