InvalidateCache ポリシー

キャッシュから値を削除する方法を構成します。

このポリシーは、キャッシュに汎用的な目的で短期間保存する場合に使用します。Populate Cache ポリシー(エントリの書き込み)や Lookup Cache ポリシー(キャッシュ内のエントリの読み込み)と組み合わせて使用します。

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

要素リファレンス

このポリシーで構成できる要素は次のとおりです。

    <InvalidateCache async="false" continueOnError="false" enabled="true" name="policy-name">
        <DisplayName>Policy Name</DisplayName>
        <CacheKey>
            <Prefix>prefix_string</Prefix>
            <KeyFragment ref="variable_reference"/>
            <KeyFragment>fragment_string</KeyFragment>
        </CacheKey>
        <!-- Omit this element if you're using the included shared cache. -->
        <CacheResource>cache_to_use</CacheResource>
        <Scope>scope_enumeration</Scope>
        <CacheContext>
            <APIProxyName>application_that_added_the_entry</APIProxyName>
            <ProxyName>proxy_for_which_data_was_cached</ProxyName>
            <TargetName>endpoint_for_which_data_was_cached</TargetName>
        </CacheContext>
        <PurgeChildEntries>true_to_purge_all_child_entries</PurgeChildEntries>
    </InvalidateCache>
    

<InvalidateCache> 属性

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

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

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

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

なし 必須
continueOnError

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

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

false 省略可
enabled

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

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

true 省略可
async

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

false 非推奨

<DisplayName> 要素

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

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

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

<CacheContext> / <APIProxyName> 要素

キャッシュ エントリを追加したアプリケーションの名前を指定します。

    <APIProxyName>application_that_added_the_entry</APIProxyName>
    

属性

属性 説明 デフォルト 要否
ref アプリケーション名を格納する変数。 なし 省略可 String

<CacheContext> 要素

Prefix 要素に値が指定されていない場合のキャッシュキーの作成方法を指定します。また、別の API プロキシが追加したキャッシュ エントリをクリアする方法を指定します。

    <CacheContext>
      <APIProxyName ref="variable_name">application_that_added_the_entry</APIProxyName>
      <TargetName ref="variable_name">endpoint_for_which_data_was_cached</TargetName>
      <ProxyName ref="variable_name">proxy_for_which_data_was_cached</ProxyName>
    </CacheContext>
    

CacheKey の作成に使用します。別の API プロキシが追加したキャッシュ エントリをクリアするときに CacheKey プレフィックス(カスタム プレフィックス)を使用しない場合は、APIProxyName、ProxyName、TargetName の値は必須です。

<CacheKey> 要素

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

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

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

このポリシー(対応する PopulateCache ポリシーと LookupCache ポリシーを含む)が組み込みの共有キャッシュを使用している場合は、この要素を省略します。

    <CacheResource>cache_to_use</CacheResource>
    

デフォルト:

なし

必須?:

省略可

型:

文字列

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

<CacheKey> / <KeyFragment> 要素

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

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

デフォルト:

なし

必須?:

省略可

型:

なし

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

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

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

属性

属性 説明 デフォルト 要否
ref 値を取得する変数。この要素にリテラル値が含まれている場合は使用できません。 なし 省略可 String

<CacheKey> / <Prefix> 要素

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

    <Prefix>prefix_string</Prefix>
    

デフォルト:

なし

必須?:

省略可

型:

文字列

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

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

<CacheContext> / <ProxyName> 要素

データをキャッシュに保存したプロキシの名前を指定します。

    <ProxyName>proxy_for_which_data_was_cached</ProxyName>
    

デフォルト:

なし

必須?:

省略可

型:

String

属性

属性 説明 デフォルト 要否
ref 値を取得する変数。この要素にリテラル値が含まれている場合は使用できません。 なし 省略可 String

<PurgeChildEntries> 要素

true に設定すると、このポリシーに構成された <KeyFragment> 要素の値を共有するキャッシュ エントリが削除されます。キャッシュキーの他の部分の値(<Prefix> 要素など)は考慮されません。

<KeyFragment> 要素は必須です。この要素を指定せずに <PurgeChildEntries> を true に設定すると、キャッシュ内のすべてのエントリが削除されます。

同じキー フラグメント値を持つキャッシュ エントリをすべて無効にすると、複数の関連エントリを同時に削除できます。

    <PurgeChildEntries>true_to_purge_child_entries</PurgeChildEntries>
    

デフォルト:

false

必須?:

省略可

型:

Boolean

<Scope> 要素

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

    <Scope>scope_enumeration</Scope>
    

デフォルト:

「Exclusive」

要否:

省略可

型:

文字列

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

orgName__envName__applicationName__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__applicationName の形式で先頭に追加されます。

Proxy

ProxyEndpoint 構成がプレフィックスとして使用されます。

キャッシュキーが orgName__envName__applicationName__deployedRevisionNumber__proxyEndpointName 形式で先頭に追加されます。

Target

TargetEndpoint 構成がプレフィックスとして使用されます。

キャッシュキーが、orgName__envName__applicationName__deployedRevisionNumber__targetEndpointName の形式で先頭に追加されます。

Exclusive

デフォルト。これが最も特定的なスコープであるため、特定のキャッシュ内で名前空間が競合するリスクが最小限になります。

接頭辞は次のいずれかの形式をとります。

  • ポリシーが ProxyEndpoint フローに接続されている場合、接頭辞は ApiProxyName_ProxyEndpointName の形式になります。
  • ポリシーが TargetEndpoint に接続されている場合、接頭辞は ApiProxyName_TargetName の形式になります。

キャッシュキーは、orgName__envName__applicationName__deployedRevisionNumber__proxyNameITargetName の形式で先頭に追加されます。

たとえば、完全な文字列は次のようになります。


    apifactory__test__weatherapi__16__default__apiAccessToken
    

<CacheContext> / <TargetName> 要素

データをキャッシュに保存したターゲット エンドポイントの名前を指定します。

    <TargetName>endpoint_for_which_data_was_cached</TargetName>
    

デフォルト:

なし

必須?:

省略可

型:

String

属性

属性 説明 デフォルト 要否
ref 値を取得する変数。この要素にリテラル値が含まれている場合は使用できません。 なし 省略可 文字列

使用上の注意

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

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

エラーコード

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

エラーコードの接頭辞

なし

ランタイム エラー

このポリシーはランタイム エラーをスローしません。

デプロイエラー

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

エラー名 原因 修正
InvalidCacheResourceReference API プロキシがデプロイされている環境に存在しない名前が InvalidateCache ポリシーの <CacheResource> 要素に設定されていると、このエラーが発生します。 build
CacheNotFound このエラーは、エラー メッセージに記載されている特定のキャッシュが特定の Message Processor コンポーネント上に作成されていない場合に発生します。 build

障害変数

なし

エラー レスポンスの例

なし