PopulateCache ポリシー

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

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

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

要素リファレンス

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

    <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>
            <TimeoutInSec>300</TimeoutInSec>
        </ExpirySettings>
        <Source>flowVar</Source>
    </PopulateCache>
    

<PopulateCache> 属性

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

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

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

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

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

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

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

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

true 省略可
async

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

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

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

デフォルト:

なし

必須?:

省略可

型:

文字列

キャッシュを構成する方法について詳しくは、環境キャッシュの作成と編集をご覧ください。

<ExpirySettings>/<ExpiryDate> 要素

キャッシュ エントリの有効期限の日付を指定する要素です。mm-dd-yyyy の形式を使用します。

    <ExpirySettings>
        <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
    </ExpirySettings>
    

デフォルト:

なし

必須?:

省略可

型:

String

属性

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

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

なし 省略可 文字列

<ExpirySettings> 要素

キャッシュ エントリの有効期限を指定する要素です。この要素が存在する場合、<TimeoutInSec><TimeOfDay><ExpiryDate> の両方をオーバーライドします。

    <ExpirySettings>
      <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
      <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
      <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
    </ExpirySettings>
    

デフォルト:

なし

必須?:

必須

型:

なし

<CacheKey>/<KeyFragment> 要素

キャッシュキーに含める値を指定する要素です。この値を使用して、リクエストをキャッシュに保存されたレスポンスと照合するための名前空間が作成されます。

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

デフォルト:

なし

必須?:

省略可

型:

なし

この要素には、キー(ユーザーが指定する静的な名前)または値(変数を参照して動的に設定されるエントリ)を指定できます。指定されたすべてのフラグメント(および接頭辞)が連結されてキャッシュキーが作成されます。

    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
    

<KeyFragment> 要素は、<Prefix> および <Scope> とあわせて使用します。詳しくは、キャッシュキーの使用をご覧ください。

属性

属性 デフォルト 必須 説明
ref 文字列 ×

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

<CacheKey>/<Prefix> 要素

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

    <Prefix>prefix_string</Prefix>
    

デフォルト:

なし

必須?:

省略可

型:

文字列

<Scope> 列挙値ではなく独自の値を指定するには、<Scope> の代わりにこの要素の値を使用します。この要素が定義されている場合、<Prefix> によって、キャッシュに書き込まれたエントリの先頭にキャッシュキー値が付加されます。<Prefix> 要素の値は <Scope> 要素の値をオーバーライドします。

<Prefix> 要素は、<CacheKey> および <Scope> とあわせて使用します。詳しくは、キャッシュキーの使用をご覧ください。

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

デフォルト:

なし

必須?:

必須

型:

文字列

<ExpirySettings>/<TimeOfDay> 要素

キャッシュ エントリの有効期限が切れる時刻を指定する要素です。HH:mm:ss の形式を使用します。この要素が存在する場合、この要素の兄弟 <TimeoutInSec><TimeOfDay> をオーバーライドします。

時刻は HH:mm:ss の形式で入力します。HH は 24 時間制の時間を表します。たとえば、午後 2 時 30 分の場合は 14:30:00 と入力します。

時刻のデフォルトのロケールとタイムゾーンは、コードが実行される場所によって異なります(ポリシーの構成時には確定していません)。ロケールの構成については、環境キャッシュの作成と編集をご覧ください。

    <ExpirySettings>
        <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
    </ExpirySettings>
    

デフォルト:

なし

必須?:

省略可

型:

String

属性

属性 説明 デフォルト 要否
ref 有効期限の時刻の値を格納する変数。 なし 省略可 文字列

<ExpirySettings> / <TimeoutInSec> 要素

キャッシュ エントリが期限切れになるまでの秒数を指定する要素です。

    <ExpirySettings>
        <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
    </ExpirySettings>
    

デフォルト:

なし

必須?:

省略可

型:

整数

属性

属性 説明 デフォルト 要否
ref タイムアウト値を格納する変数。
なし
省略可 文字列

使用上の注意

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

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

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

基盤となるデータストアについて詳しくは、キャッシュの仕組みをご覧ください。キャッシュを構成する方法について詳しくは、環境キャッシュの作成と編集をご覧ください。

エラーコード

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

ランタイム エラー

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

障害コード HTTP ステータス 発生する状況
policies.populatecache.EntryCannotBeCached 500 エントリはキャッシュできません。キャッシュされるメッセージ オブジェクトは、シリアライズ可能なクラスのインスタンスではありません。

デプロイエラー

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

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

障害変数

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

変数 説明
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>