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 に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について） 現在のフローにおける障害処理	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> 注: 時刻は、協定世界時（UTC）のタイムゾーンで指定します。 PopulateCache の時刻表記は、国際標準 ISO 8601 で定義されている国際標準の日付表記に準拠しています。

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

上記の <ExpirySettings> のそれぞれの子要素で、子要素にオプションの ref 属性を指定すると、ポリシーは指定されたコンテキスト変数から有効期限値を取得します。変数が定義されていない場合、ポリシーは子要素のリテラル テキスト値を使用します。

<Scope> 要素

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

<Scope>scope_enumeration</Scope>

デフォルト:	Exclusive
要否:	省略可
型:	文字列

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

orgName__envName__apiProxyName__deployedRevisionNumber__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__deployedRevisionNumber__proxyEndpointName の形式で値の先頭に追加されます。
Target	TargetEndpoint 構成が接頭辞として使用されます。 キャッシュキーは、orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName の形式で値の先頭に追加されます。
Exclusive	デフォルト。これが最も特定的なスコープであるため、任意のキャッシュ内で名前空間が競合するリスクが最小限になります。 接頭辞は次のいずれかの形式をとります。 ポリシーが ProxyEndpoint フローに接続されている場合、接頭辞は ApiProxyName_ProxyEndpointName の形式になります。 ポリシーが TargetEndpoint に接続されている場合、接頭辞は ApiProxyName_TargetName の形式になります。 キャッシュキーは、orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName の形式で値の先頭に追加されます。 たとえば、完全な文字列は次のようになります。 apifactory__test__weatherapi__16__default__apiAccessToken

<Source> 要素

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

<Source>source_variable</Source>

デフォルト:	なし
要否:	必須
型:	文字列

注:

• JSON オブジェクトはメモリ内キャッシュ（L1）にのみ保存されます。
• これらのオブジェクトを永続キャッシュ（L2）に保存する場合は、オブジェクトを文字列形式にシリアル化することをおすすめします。
• これにより、L2 キャッシュを効果的に利用し、キャッシュ効率を最大化できます。
• 詳細については、キャッシュの仕組みをご覧ください。
  

使用上の注意

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

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

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

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

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

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

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード	HTTP ステータス	発生条件
policies.populatecache.EntryCannotBeCached	500	エントリをキャッシュできない場合。キャッシュされるメッセージ オブジェクトが、シリアル化可能なクラスのインスタンスではない場合。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

ヒント: エラーの解決にサポートが必要な場合は、「修正」列の をクリックして、詳しいトラブルシューティング情報をご覧ください。

エラー名	原因	修正
InvalidCacheResourceReference	このエラーは、API プロキシがデプロイされている環境に存在しない名前が PopulateCache ポリシーの <CacheResource> 要素に設定されている場合に発生します。
CacheNotFound	<CacheResource> 要素で指定されたキャッシュが存在しません。

障害変数

このポリシーがエラーをトリガーした場合は、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数	説明	例
fault.name="fault_name"	fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name は、障害が発生したポリシーのユーザー指定の名前です。	populatecache.POP-CACHE-1.failed = true

エラー レスポンスの例

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

障害ルールの例

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