
キャッシュに保存された値を実行時に取り出す方法を構成します。
このポリシーは、キャッシュに汎用的な目的で短期間保存する場合に使用します。Populate Cache ポリシー(エントリの書き込み)や Invalidate Cache ポリシー(エントリの無効化)と併せて使用します。
バックエンド リソースのレスポンスのキャッシュ保存については、Response Cache ポリシーをご覧ください。
要素リファレンス
このポリシーで構成できる要素を次に示します。
<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1"> <DisplayName>Lookup Cache 1</DisplayName> <Properties/> <CacheKey> <Prefix/> <KeyFragment ref=""/> </CacheKey> <!-- Omit this element if you're using the included shared cache. --> <CacheResource/> <CacheLookupTimeoutInSeconds/> <Scope>Exclusive</Scope> <AssignTo>flowVar</AssignTo> </LookupCache>
共有キャッシュはデフォルトで含まれています。共有キャッシュを使用するには、このポリシー構成で <CacheResource>
要素を省略します。
基盤となるデータストアについて詳しくは、キャッシュの仕組みをご覧ください。キャッシュの構成について詳しくは、環境キャッシュの作成と編集をご覧ください。
<LookupCache> 属性
次の表に、ポリシーのすべての親要素に共通の属性を記載します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
name |
ポリシーの内部名。 必要に応じて、管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗した場合にエラーを返すには、 ポリシーが失敗してもフロー実行を続行するには、 |
false | 省略可 |
enabled |
ポリシーを適用するには ポリシーを無効にするには |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
name
属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。
<DisplayName>Policy Display Name</DisplayName>
デフォルト: |
なし この要素を省略した場合、ポリシーの |
要否: | 省略可 |
型: | 文字列 |
<AssignTo> 要素
キャッシュからキャッシュ エントリを取り出した後、それが割り当てられる変数を指定します。変数は書き込み可能でなければなりません。キャッシュ ルックアップで値が得られない場合、変数は設定されません。
<AssignTo>variable_to_receive_cached_value</AssignTo>
デフォルト: |
なし |
要否: |
必須 |
型: |
文字列 |
<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>
と組み合わせて使用します。詳細については、キャッシュキーの使用をご覧ください。
<CacheLookupTimeoutInSeconds> 要素
キャッシュ ルックアップが失敗してから、キャッシュミスとみなすまでの秒数を指定します。キャッシュミスとみなされると、キャッシュミス パスに沿ってフローが再開されます。
<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>
デフォルト: |
30 |
要否: |
省略可 |
型: |
整数 |
<CacheResource> 要素
メッセージを保存するキャッシュを指定します。
このポリシー(および対応する PopulateCache ポリシーと InvalidateCache ポリシー)が、あらかじめ用意された共有キャッシュを使用している場合は、この要素を完全に省略します。
<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 | 文字列 | × |
値を取得する変数。この要素にリテラル値が含まれている場合は使用できません。 |
<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__applicationName__deployedRevisionNumber__proxy|TargetName__
[ serializedCacheKey ] になります。
<Prefix>
要素が <CacheKey>
に含まれている場合、この要素の値が <Scope>
要素の値を置き換えます。有効な値には、以下の列挙値が含まれます。
<Scope>
要素は <CacheKey>
や <Prefix>
と組み合わせて使用します。詳細については、キャッシュキーの使用をご覧ください。
有効な値
Global |
キャッシュキーが、環境にデプロイされているすべての API プロキシで共有されます。キャッシュキーは、orgName __ envName __ の形式で値の先頭に付加されます。
|
Application |
API プロキシ名が接頭辞として使用されます。 キャッシュキーは orgName__envName__applicationName という形式で値の先頭に付加されます。 |
Proxy |
ProxyEndpoint 構成が接頭辞として使用されます。 キャッシュキーは、orgName__envName__applicationName__deployedRevisionNumber__proxyEndpointName という形式で値の先頭に付加されます。 |
Target |
TargetEndpoint 構成が接頭辞として使用されます。 キャッシュキーは orgName__envName__applicationName__deployedRevisionNumber__targetEndpointName という形式で値の先頭に付加されます。 |
Exclusive |
デフォルト。これが最も特定的なスコープであるため、特定のキャッシュ内で名前空間が競合するリスクが最小限になります。 接頭辞は次のいずれかの形式をとります。
キャッシュキーは、orgName__envName__applicationName__deployedRevisionNumber__proxyNameITargetName という形式で値の先頭に付加されます。 たとえば、完全な文字列は次のようになります。 apifactory__test__weatherapi__16__default__apiAccessToken. |
使用上の注意
このポリシーは汎用キャッシュに使用します。実行時には、LookupCache ポリシーがキャッシュから値を取り出し、AssignTo 要素で指定した変数に代入します(値が取り出せない場合、変数は設定されません)。CacheKey 要素と Scope 要素をつないで形成されるキャッシュキーに基づいて、値を探します。つまり、PopulateCache ポリシーによってキャッシュに追加された特定の値を取り出すには、LookupCache ポリシーのキャッシュキー関連の要素が PopulateCache ポリシーと同じ形で構成されている必要があります。
Populate Cache ポリシー、LookupCache ポリシー、InvalidateCache ポリシーが使用する汎用キャッシュは、ユーザーが構成するキャッシュか、デフォルトで含まれる共有キャッシュのどちらかです。ほとんどの場合、基盤となる共有キャッシュで十分なはずです。デフォルトのキャッシュを使用するには、<CacheResource>
要素を省略します。
キャッシュの構成方法については、環境キャッシュの作成と編集をご覧ください。基盤となるデータストアについて詳しくは、キャッシュの仕組みをご覧ください。
フロー変数
フロー変数を使用すると、HTTP ヘッダー コンテンツ、メッセージ コンテンツ、またはフローのコンテキストに基づいて、ポリシーとフローが実行時に動的に動作するよう構成できます。フロー変数の詳細については、変数リファレンスをご覧ください。
LookupCache ポリシーで定義したキャッシュの振る舞いをカスタマイズすると、次の事前定義されたフロー変数が使用可能になります。
変数 | 型 | 権限 | 説明 |
---|---|---|---|
lookupcache.{policy-name}.cachename | 文字列 | 読み取り専用 | ポリシーで使用されているキャッシュ名を返します。 |
lookupcache.{policy-name}.cachekey | 文字列 | 読み取り専用 | 使用されたキーを返します。 |
lookupcache.{policy-name}.cachehit | ブール値 | 読み取り専用 | 指定されたキャッシュキーの値をポリシーが検出した場合は true。 |
lookupcache.{policy-name}.assignto | 文字列 | 読み取り専用 | キャッシュが割り当てられている変数を返します。 |
エラーコード
This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.
Error code prefix
N/A
Runtime errors
This policy does not throw any runtime errors.
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 is set to a
name which does not exist in the environment where the API proxy is being deployed. |
build |
InvalidTimeout |
If the <CacheLookupTimeoutInSeconds> element is set to
a negative number, then the deployment of the API proxy fails. |
build |
CacheNotFound |
This error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component. | build |
Fault variables
N/A
Example error response
N/A