PopulateCache ポリシー

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

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

キャッシュに保存された値がランタイム時に書き込まれる方法を構成します。

PopulateCache ポリシーは、短期の汎用キャッシュにエントリを書き込むために設計されています。このポリシーは、LookupCache ポリシー（キャッシュ エントリの読み取りに関するポリシー）および InvalidateCache ポリシー（エントリの無効化に関するポリシー）と組み合わせて使用します。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

バックエンド リソースのレスポンスのキャッシュ保存については、ResponseCache ポリシーをご覧ください。

要素リファレンス

このポリシーで構成できる要素を次に示します。

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

<PopulateCache> 属性

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

属性 説明 デフォルト 要否
name

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

 なし 必須
continueOnError

ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。

ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連項目:

 false 省略可
enabled

ポリシーを適用するには、true に設定します。

ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。

 true 省略可
async

この属性は非推奨となりました。

 false 非推奨

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>
デフォルト

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。
要否 省略可
タイプ 文字列

<CacheKey> 要素

キャッシュに保存されているデータを参照する一意のポインタを構成します。

キャッシュキーのサイズは 2 KB に制限されています。

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

デフォルト:

なし

要否:

 必須

型:

なし

<CacheKey> はキャッシュに保存される各データの名前を構成します。

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

<CacheResource> 要素

メッセージを保存するキャッシュを指定します。

このポリシー（および対応する LookupCache ポリシーと InvalidateCache ポリシー）があらかじめ用意された共有キャッシュを使用している場合は、この要素を完全に省略します。

<CacheResource>cache_to_use</CacheResource>

デフォルト:

なし

要否:

 省略可

型:

文字列

キャッシュの構成方法については、汎用キャッシュをご覧ください。

<CacheKey>/<KeyFragment> 要素

キャッシュキーに含める値を指定します。ref 属性で参照解除する変数、または固定値を指定します。

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

デフォルト:

なし

要否:

 0 以上。

型:

なし

Apigee はランタイムに、<Scope> 要素または <Prefix> 要素から取得した値を先頭に付加して、各 <KeyFragment> 要素の解決された値を連結してキャッシュキーを作成します。詳細については、キャッシュキーの使用をご覧ください。

属性

属性 型 デフォルト 必須 説明
ref 文字列 いいえ

値を取得する変数。この要素にリテラル値が含まれている場合は、使用できません。

<CacheKey>/<Prefix> 要素

キャッシュキーの接頭辞として使用する固定値を指定する要素です。

<Prefix>prefix_string</Prefix>

デフォルト:

なし

要否:

 省略可

型:

文字列

<Prefix> 要素は <Scope> 要素をオーバーライドします。

Apigee はランタイムに、<Scope> 要素または <Prefix> 要素から取得した値を先頭に付加して、各 <KeyFragment> 要素の解決された値を連結してキャッシュキーを作成します。詳細については、キャッシュキーの使用をご覧ください。

<ExpirySettings> 要素

キャッシュ エントリの有効期限を指定します。

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

デフォルト:

なし

要否:

 必須

型:

なし

<ExpirySettings> の子要素

子要素は 1 つだけ使用します。次の表に、<ExpirySettings> の子要素の説明を示します。

子要素 説明
<TimeoutInSeconds>

キャッシュ エントリが期限切れになるまでの秒数。

<ExpirySettings>
  <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds>
</ExpirySettings>

この要素は、サポートが終了した TimeoutInSec 要素に代わるものです。
<ExpiryDate>

キャッシュ エントリの有効期限の日付を指定します。mm-dd-yyyy の形式で文字列を指定します。

<ExpirySettings>
  <ExpiryDate ref="var-containing-date">expiry</ExpiryDate>
</ExpirySettings>

過去の日付を指定した場合、ポリシーによってキャッシュされたエントリに最大有効期間が適用されます。上限は 30 日です。
<TimeOfDay>

キャッシュ エントリの有効期限の時刻を指定する要素です。 HH:mm:ss の形式で文字列を指定します。ここで、HH は UTC タイムゾーンの 24 時間制の時間を表します。たとえば、14:30:00 は午後 2 時 30 分を意味します。

<ExpirySettings>
  <TimeOfDay ref="var-containing-time">expiry</TimeOfDay>
</ExpirySettings>

子要素は 1 つのみ指定してください。複数の要素を指定する場合の優先順位は、TimeoutInSeconds、ExpiryDate、TimeOfDay です。

上記の <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

<Source> 要素

キャッシュに書き込む必要がある値を持つ変数を指定します。

<Source>source_variable</Source>

デフォルト:

なし

要否:

 必須

型:

文字列

使用上の注意

このポリシーは汎用キャッシュに使用します。ランタイムで、<PopulateCache> ポリシーでは <Source> 要素で指定した変数から <CacheResource> 要素で指定したキャッシュにデータを書き込みます。<CacheKey>、<Scope>、<Prefix> 要素を使用して、<LookupCache> ポリシーから値を取得するために使用できるキーを指定できます。<ExpirySettings> 要素を使用して、キャッシュに保存される値の有効期限を構成します。

PopulateCache ポリシー、LookupCache ポリシー、InvalidateCache ポリシーで汎用キャッシュを使用する場合、ユーザーが構成したキャッシュかデフォルトの共有キャッシュが使用されます。ほとんどの場合、基盤となる共有キャッシュで十分です。このキャッシュを使用する場合は、<CacheResource> 要素を省略します。

キャッシュの制限: さまざまなキャッシュの制限が適用されます（名前や値のサイズ、キャッシュの合計数、キャッシュのアイテム数、有効期間など）。

基盤となるデータストアについて詳しくは、キャッシュの内部をご覧ください。

キャッシュの暗号化について

Apigee と Apigee ハイブリッド（バージョン 1.4 以降）: キャッシュと KVM データは常に暗号化されます。

エラーコード

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP Status Occurs when
policies.populatecache.EntryCannotBeCached 500 An entry cannot be cached. The message object being cached is not an instance of a class that is Serializable.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidCacheResourceReference This error occurs if the <CacheResource> element in the PopulateCache policy is set to a name that does not exist in the environment where the API proxy is being deployed.
CacheNotFound The cache specified in the <CacheResource> element does not exist.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. populatecache.POP-CACHE-1.failed = true

Example error response

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

Example fault rule

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>