概要
Apigee Edge で利用可能な Key-Value マップ(KVM)ストアへのポリシーベースのアクセス権を提供します。Key-Value ペアは、PUT、GET、または DELETE の操作を指定する KeyValueMapOperations ポリシーを構成して、既存の名前付きマップから保存、取得、削除を行えます(これらの操作の少なくとも 1 つは、ポリシーによって実行する必要があります)。
動画
KVM の詳細については、次の動画をご覧ください。
動画 | 説明 |
---|---|
Key-Value マップが必要な理由 | KVM が必要な理由とその仕組みについて説明します。 |
UI を使用して KVM を作成し、ランタイム時に KVM を取得する | KVM を作成し、KVM ポリシーを使用してその値を取得し、フロー変数を使用してその値を API リクエストに注入します。 |
API ランタイム時に KVM の作成と更新を行う | KVM ポリシーを使用して API ランタイム中に KVM を作成します。 |
KVM をキャッシュしパフォーマンスを向上させる | データをキャッシュすることにより、KVM ポリシーのパフォーマンスを向上させます。 |
暗号化された KVM を保存する | 機密情報を KVM に暗号化形式で保存し、実行時に KVM ポリシーとプライベート変数を使用して値を取得します。 |
KVM スコープを使用してアクセスを管理する | KVM ポリシー スコープ属性を使用して、KVM を組織、環境、API プロキシ、または API プロキシ リビジョンに制限します。 |
API ランタイム時に KVM エントリを削除する | KVM ポリシーの DELETE 操作で、API ランタイムの KVM エントリを削除します。 |
サンプル
リテラルで KVM を PUT
次のポリシーが実行されると、FooKVM
という Key-Value マップが作成され、(変数から抽出された値で設定されていない)リテラル文字列 foo,bar
で設定された 2 つの値を持つ、FooKey_1
の名前付きキーが作成されます(次の例でキーを GET するときは、必要な値を取得するためにインデックス番号を指定します)。
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="CreateFooKVM" mapIdentifier="FooKVM"> <DisplayName>CreateFooKVM</DisplayName> <ExpiryTimeInSecs>86400</ExpiryTimeInSecs> <Scope>environment</Scope> <Put> <Key> <Parameter>FooKey_1</Parameter> </Key> <Value>foo</Value> <Value>bar</Value> </Put> </KeyValueMapOperations>
スコープは「環境」です。つまり、管理 UI の [APIs] > [Environment Configuration] > [Key Value Maps] で KVM を確認できます。そのページに表示される KVM は、すべて選択した環境にスコープ設定されます。
リテラルから KVM を GET
このポリシーは、前の例の FooKVM
マップを調べ、FooKey_1
キーから 2 番目の値(index = "2")を取得し、foo_variable
と呼ばれる変数に保存します。
<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM"> <DisplayName>GetKVM</DisplayName> <ExpiryTimeInSecs>86400</ExpiryTimeInSecs> <Scope>environment</Scope> <Get assignTo="foo_variable" index="2"> <Key> <Parameter>FooKey_1</Parameter> </Key> </Get> </KeyValueMapOperations>
変数で KVM を PUT
Key-Value マップの有用かつ簡単な利用例は、URL 短縮サービスです。Key-Value マップは、短縮 URL と対応する完全 URL を保存するように構成できます。
このポリシー サンプルで、Key-Value マップが作成されます。ポリシーは 2 つの関連する値を持つキーを "urlMapper" という名前の Key-Value マップに PUT します。
<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper"> <Scope>apiproxy</Scope> <Put override="true"> <Key> <Parameter ref="urlencoding.requesturl.hashed"/> </Key> <Value ref="urlencoding.longurl.encoded"/> <Value ref="request.queryparam.url"/> </Put> </KeyValueMapOperations>
この例のキー urlencoding.requesturl.hashed
は、カスタム変数の例です。ハッシュされたリクエスト URL は、コード(JavaScript や Java など)によって生成され、KeyValueMapOperations ポリシーがアクセスできる、この変数に保存されます。
キー requesturl.hashed
ごとに、2 つの値が保存されます。
urlencoding.longurl.encoded
という名前のカスタム変数の内容- 事前定義変数
request.queryparam.url
の内容
たとえば、ポリシーがランタイム時に実行される場合、変数の値は次のようになります。
urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
request.queryparam.url: http://apigee.com
次の Key-Value マップとエントリが、Edge の Key-Value ストアで生成され、ポリシーを適用する API プロキシにスコープ設定されます。
{ "entry" :[ { "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be", "value" : "http://tinyurl.com/38lwmlr,http://apigee.com" } ], "name" : "urlMapper" }
エントリは削除されるまで保持されます。Key-Value ストアエントリは、クラウドを実行している Edge のインスタンス間で分散されます。
変数から KVM を GET
Key-Value マップの有用かつ簡単な利用例は、URL 短縮サービスです。Key-Value マップは、短縮 URL と対応する完全 URL を保存するように構成できます。
KeyValueMapOperations PUT タブの対象になっているような Key-Value マップエントリの値を取得するには、次のように Key-Value マップを取得するようにポリシーを構成します。
<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper"> <Scope>apiproxy</Scope> <Get assignTo="urlencoding.shorturl" index='1'> <Key> <Parameter ref="urlencoding.requesturl.hashed"/> </Key> </Get> </KeyValueMapOperations>
このポリシーが実行されると、urlencoding.requesturl.hashed
変数の値が ed24e12820f2f900ae383b7cc4f2b31c402db1be
の場合は、urlencoding.shorturl
という名前のカスタム変数が、値 http://tinyurl.com/38lwmlr
で設定されます。
データが取得されたので、他のポリシーおよびコードは、それらの変数から値を抽出することによって、そのデータにアクセスできます。
KVM から暗号化された値を GET
Key-Value マップが暗号化されている場合は、assignTo
属性値で「private.
」接頭辞を使用して値を取得します。この例では、変数 private.encryptedVar
が Key-Value マップの foo
キーの復号された値を保持します。暗号化された Key-Value マップの作成については、Key-Value Maps management API の「作成」トピックをご覧ください。
<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map"> <Scope>apiproxy</Scope> <Get assignTo="private.encryptedVar" index='1'> <Key> <Parameter>foo</Parameter> </Key> </Get> </KeyValueMapOperations>
データが取得されたので、他のポリシーおよびコードは、その変数から値を抽出することによって、そのデータにアクセスできます。
要素リファレンス
要素リファレンスでは、KeyValueMapOperations の要素と属性について説明します。
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="urlMapper" > <DisplayName>Key Value Map Operations 1</DisplayName> <Scope>environment</Scope> <ExpiryTimeInSecs>300</ExpiryTimeInSecs> <InitialEntries> <Entry> <Key> <Parameter>key_name_literal</Parameter> </Key> <Value>value_literal</Value> </Entry> <Entry> <Key> <Parameter>variable_name</Parameter> </Key> <Value>value_1_literal</Value> <Value>value_2_literal</Value> </Entry> </InitialEntries> <Put override="false"> <Key> <Parameter>key_name_literal</Parameter> </Key> <Value ref="variable_name"/> </Put> <Get assignTo="myvar" index="1"> <Key> <Parameter ref="variable_name"/> </Key> </Get> <Delete> <Key> <Parameter>key_name_literal</Parameter> </Key> </Delete> </KeyValueMapOperations>
<KeyValueMapOperations> 属性
次の例は、<KeyValueMapOperations>
タグの属性を示しています。
<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">
次の表に、<KeyValueMapOperations>
タグに固有の属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
mapIdentifier |
このポリシーまたは管理 UI で作成されたマップにアクセスするときに使用する識別子を指定します。 Apigee Edge for Public Cloud では、KVM 名で大文字と小文字が区別されます。たとえば、 この属性を除外すると、 組織 / 環境 / API プロキシのスコープ内で、 |
なし | 省略可 |
次の表に、すべてのポリシーの親要素に共通する属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
name |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗した場合にエラーを返すには、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name
属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
デフォルト |
なし この要素を省略した場合、ポリシーの |
---|---|
要否 | 省略可 |
タイプ | 文字列 |
<Delete> 要素
指定された Key-Value ペアを削除します。<Get>
、<Put>
、<Delete>
のうち、少なくとも 1 つを使用する必要があります。
親要素の mapIdentifier
属性で必ず KVM の名前を指定してください。次に例を示します。
<Delete> <Key> <Parameter>key_name_literal</Parameter> </Key> </Delete>
デフォルト | なし |
---|---|
要否 | <Get> または <Put> が存在しない場合は必須です。 |
型 | なし |
<Entry> 要素
KeyValueMap のシード値。この値は、初期化時に KeyValueMap に代入されます。
Edge for Public Cloud の場合、キーサイズは 2 KB に制限されています。例:
<InitialEntries> <Entry> <Key> <Parameter>key_name_literal</Parameter> </Key> <Value>v1</Value> </Entry> <Entry> <Key> <Parameter>key_name_variable</Parameter> </Key> <Value>v3</Value> <Value>v4</Value> </Entry> </InitialEntries>
デフォルト | なし |
---|---|
要否 | 省略可 |
型 | なし |
<ExclusiveCache> 要素
非推奨。代わりに <Scope>
要素を使用してください。
<ExpiryTimeInSecs> 要素
指定した KVM からキャッシュされた値を Edge が更新するまでの時間を秒単位で指定します。
0 または -1 の値、またはこの要素を除外すると、デフォルト値の 300 秒が使用されます。例:
<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
デフォルト | 300 (5 分) |
---|---|
要否 | 省略可 |
型 | 整数 |
KVM は、キーと値を NoSQL データベースに保存する、長期的な永続性メカニズムです。そのため、実行時に KVM から読み込むと、プロキシのパフォーマンスが低下する可能性があります。パフォーマンスを向上させるため、Edge には、実行時に KVM Key-Value をメモリにキャッシュするためのメカニズムが組み込まれています。この KVM Operations ポリシーは、GET 操作のため、常にキャッシュから読み取ります。
<ExpiryTimeInSecs>
要素を使用すると、ポリシーで使用される Key-Value を KVM から再度更新するまでキャッシュに保存する期間を制御できます。ただし、GET 操作と PUT 操作ではキャッシュの有効期限にもたらす影響が異なります。
GET - KVM GET 操作が初めて実行されるとき、(名前がポリシーのルート mapIdentifier
属性で指定されている)KVM からリクエストされた Key-Value がキャッシュにロードされ、その後の GET 操作のため、次のいずれかが行われるまで保持されます。
<ExpiryTimeInSecs>
に指定された秒数後に期限切れになります。
または- KVM ポリシーの PUT 操作は、(次で説明される)既存の値を上書きします。
PUT - PUT 操作は、Key-Value を指定された KVM に書き込みます。PUT がすでにキャッシュに存在するキーに書き込む場合、そのキャッシュはすぐに更新され、ポリシーの <ExpiryTimeInSecs>
要素で指定された秒数の間、新しい値を保持します。
例 - KVM のキャッシュ保存
- GET 操作は、値「10」をキャッシュに追加する「rating」の値を取得します。ポリシーに対する
<ExpiryTimeInSecs>
は 60 です。 - 30 秒後、GET ポリシーが再度実行され、キャッシュから「10」が取得されます。
- 5 秒後、PUT ポリシーは「rating」の値を「8」に更新し、PUT ポリシーに対する
<ExpiryTimeInSecs>
は 20 になります。キャッシュはすぐに新しい値で更新され、20 秒間キャッシュに残るように設定されます(PUT が実行されなかった場合、最初の GET によって最初に代入されたキャッシュは、元の 60 秒の残りの 30 秒間さらに存在します)。 - 15 秒後、別の GET が実行され、値「8」が取得されます。
<Get> 要素
指定されたキーの値を取得します。<Get>
、<Put>
、<Delete>
のうち、少なくとも 1 つを使用する必要があります。
親要素の mapIdentifier
属性で必ず KVM の名前を指定してください。
ポリシーに複数の Get
ブロックを含めると、KVM から複数のアイテムを取得できます。
デフォルト | なし |
---|---|
要否 | <Put> または <Delete> が存在しない場合は必須です。 |
型 | なし |
KVM から単一項目を取得する
<Get assignTo="myvar" index="1"> <Key> <Parameter>key_name_literal</Parameter> </Key> </Get>
KVM から複数の項目を取得する
次の例では、以下のキーと値を持つ KVM を想定しています。KVM は、最も人気のある映画のリストを常時保存することに加えて、すべての主要な映画の監督の名前を保存します。
キー | 値 |
---|---|
top_movies | Princess Bride,The Godfather,Citizen Kane |
Citizen Kane | Orson Welles |
Princess Bride | Rob Reiner |
The Godfather | Francis Ford Coppola |
現在最も人気のある映画と監督の名前を取得するために使用できる KVM ポリシーの構成を示します。
<Get assignTo="top.movie.pick" index="1"> <Key> <Parameter>top_movies</Parameter> </Key> </Get> <Get assignTo="movie.director"> <Key> <Parameter ref="top.movie.pick"/> </Key> </Get>
API プロキシが呼び出されると、Edge は API プロキシフローで使用できる次の変数を作成します。
top.movie.pick=Princess Bride
movie.director=Rob Reiner
属性
次の表に、<Get>
要素の属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
assignTo |
取得した値を割り当てる変数。 Key-Value マップが暗号化されている場合は、assignTo 名を「 <Get assignTo="private.myvar"> 接頭辞を使用せずに暗号化された Key-Value マップを取得しようとすると、ポリシーはエラーを返します。この接頭辞はデバッグ時の基本的なセキュリティのために必要であり、API プロキシ トレースおよびデバッグ セッションで暗号化された値をマスクします。 暗号化された Key-Value マップの作成については、Key-Value Maps management API と環境 Key-Value マップの作成と編集の「作成」トピックをご覧ください。 |
なし | 必須 |
index |
複数の値を持つキーからフェッチする項目のインデックス番号(1 ベースのインデックス)。たとえば、 例については、サンプルの「KVM から暗号化された値を GET」タブをご覧ください。 |
なし | 省略可 |
<InitialEntries> 要素
Key-Value マップのシード値。この値は、初期化時に Key-Value マップに代入されます。親要素の mapIdentifier
属性で必ず KVM の名前を指定してください。次に例を示します。
<InitialEntries> <Entry> <Key> <Parameter>key_name_literal</Parameter> </Key> <Value>v1</Value> </Entry> <Entry> <Key> <Parameter>key_name_variable</Parameter> </Key> <Value>v3</Value> <Value>v4</Value> </Entry> </InitialEntries>
この要素を使用する場合、デプロイされたプロキシのバージョンの管理 UI にポリシーを保存する場合、または、この要素を備えるポリシーを含む API プロキシ バンドルをデプロイする場合、キーは自動的に(暗号化されずに)KVM に作成されます。ポリシー内の値が KVM 内の値と異なる場合、プロキシのデプロイ時に KVM 内の値が上書きされます。新しい Key-Value は、既存の Key-Value とともに既存の KVM に追加されます。
この要素によって代入されるキーと値は、リテラルである必要があります。たとえば、この要素内では <Parameter
ref="request.queryparam.key">
はサポートされていません。
Edge for Public Cloud では、キーサイズは 2 KB に制限されています。詳細については、Edge for Public Cloud API と Edge for Private Cloud API の違いをご覧ください。
暗号化された Key-Value マップを作成するには、Key/Value Maps management API を使用します。
デフォルト | なし |
---|---|
要否 | 省略可 |
型 | なし |
<Key> 要素
Key-Value マップエントリでキーを指定します。キーはコンポジットにできます。つまり、複数のパラメータを追加してキーを作成できます。たとえば、userID
と role
を組み合わせて key
を作成できます。例:
<Key> <Parameter>key_name_literal</Parameter> </Key>
キー名の設定方法について詳しくは、<Parameter> 要素をご覧ください。
Edge for Public Cloud では、キーサイズは 2 KB に制限されています。詳細については、Edge for Public Cloud API と Edge for Private Cloud API の違いをご覧ください。
デフォルト | なし |
---|---|
要否 | 省略可 |
型 | なし |
<Parameter> 要素
Key-Value ペアのキーを指定します。この要素は、Key-Value ペアを作成、配置、取得、削除するときの名前を指定します。
名前は以下を使用して指定できます。
-
リテラル文字列
<Key> <Parameter>literal</Parameter> </Key>
-
ref
属性を使用して、実行時に取得される変数<Key> <Parameter ref="variable_name"/> </Key>
-
リテラルと変数参照の組み合わせ
<Key> <Parameter>targeturl</Parameter> <Parameter ref="apiproxy.name"/> <Parameter>weight</Parameter> </Key>
Key 要素に複数の Parameter 要素が含まれている場合、有効なキー文字列は、各パラメータの値を連結したもので、二重のアンダースコアで結合されています。たとえば、上記の例では、apiproxy.name
変数の値が「abc1」の場合、有効なキーは targeturl__abc1__weight
です。
Key-Value エントリを取得、更新、削除する場合でも、キー名はキー値マップのキー名と一致する必要があります。ガイドラインのキー名の指定と検索をご覧ください。
デフォルト | なし |
---|---|
要否 | 必須 |
型 | 文字列 |
属性
次の表に、<Parameter>
要素の属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
ref | 作成、取得、または削除するキーの正確な名前が値に含まれている変数の名前を指定します。 | なし | 開始タグと終了タグの間にリテラル値が指定されていない場合は必須です。リテラル値が指定されている場合は禁止されます。 |
<Put> 要素
Key-Value マップが暗号化されているかいないかにかかわらず、Key-Value マップに Key-Value ペアを書き込みます。親要素の mapIdentifier
属性で指定された Key-Value マップが存在しない場合、マップは自動的に(暗号化されずに)作成されます。Key-Value マップがすでに存在する場合は、Key-Value がそのマップに追加されます。
暗号化された Key-Value マップを作成するには、Key-Value Maps Management API を使用します。UI で暗号化された環境スコープ KVM を作成するには、環境 Key-Value マップの作成と編集をご覧ください。
<Put override="false"> <Key> <Parameter ref="mykeyvar"/> </Key> <Value ref="myvalvar1"/> </Put>
デフォルト | なし |
---|---|
要否 | <Get> または <Delete> が存在しない場合は必須です。 |
型 | なし |
属性
次の表に、<Put>
要素の属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
override |
|
false |
省略可 |
<Scope> 要素
Key-Value マップのアクセシビリティの境界線を定義します。デフォルトのスコープは environment
です。つまり、デフォルトでは、マップエントリは、(テストやプロッドなどの)環境内で実行されているすべての API プロキシによって共有されます。スコープを apiproxy
に設定すると、値をマップに書き込む API プロキシによってのみ Key-Value マップのエントリにアクセスできます。
マップまたはマップエントリにアクセスするときは、マップの作成時に使用したものと同じスコープ値を指定する必要があります。たとえば、マップが apiproxy
スコープで作成された場合は、その値を取得したり、変更を加えたり、エントリを削除したりするには、apiproxy
スコープを使用する必要があります。
<Scope>environment</Scope>
デフォルト | environment |
---|---|
要否 | 省略可 |
型 | 文字列 |
有効な値: |
|
<Value> 要素
キーの値を指定します。値は、リテラル文字列として、または ref
属性を使用して、実行時に取得する変数として指定できます。
<!-- Specify a literal value --> <Value>literal<Value>
または
<!-- Specify the name of variable value to be populated at run time. --> <Value ref="variable_name"/>
また、マルチパート値を指定する、複数の <Value>
要素を含めることもできます。値は実行時に組み合わせられます。
次の例では、KVM に 2 つのキーが追加されています。
- 値が
v1,v2
のキーk1
- 値が
v3,v4
のキーk2
<InitialEntries> <Entry> <Key> <Parameter>k1</Parameter> </Key> <Value>v1</Value> <Value>v2</Value> </Entry> <Entry> <Key> <Parameter>k2</Parameter> </Key> <Value>v3</Value> <Value>v4</Value> </Entry> </InitialEntries>
次の例では、1 つのキーが 2 つの値で作成されます。組織名が foo_org
、API プロキシ名が bar
、環境が test
であるとします。
- 値が
bar,test
のキーfoo_org
<Put> <Key> <Parameter ref="organization.name"/> </Key> <Value ref="apiproxy.name"/> <Value ref="environment.name"/> </Put>
デフォルト | なし |
---|---|
要否 | 必須 |
型 | 文字列 |
属性
次の表に、<Value>
要素の属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
ref | 設定する Key-Value を含む値を持つ変数の名前を指定します。 | なし | 開始タグと終了タグの間にリテラル値が指定されていない場合は必須です。リテラル値が指定されている場合は禁止されます。 |
エラー リファレンス
Edge ポリシーから返されるエラーは、エラーコード参照で説明されている一貫した形式に従います。
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
障害コード | HTTP ステータス | 原因 | 解決方法 |
---|---|---|---|
steps.keyvaluemapoperations.SetVariableFailed |
500 |
このエラーは、暗号化された Key-Value マップから値を取得し、名前に接頭辞 |
build |
steps.keyvaluemapoperations.UnsupportedOperationException |
500 |
このエラーは、 |
build |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
エラー名 | 原因 | 解決方法 |
---|---|---|
InvalidIndex |
Key Value Map Operations ポリシーの <Get> 要素に指定された index 属性がゼロまたは負の数である場合、API プロキシのデプロイは失敗します。インデックスは 1 から始まるため、ゼロまたは負の整数のインデックスは無効と見なされます。 |
build |
KeyIsMissing |
このエラーは、<Key> 要素が完全に欠落しているか、Key Value Map Operations ポリシーの <InitialEntries> 要素の <Entry> の下の <Key> 要素に <Parameter> 要素がない場合に発生します。 |
build |
ValueIsMissing |
このエラーは、Key Value Map Operations ポリシーの <InitialEntries> 要素の <Entry> 要素の下に <Value> 要素がない場合に発生します。 |
build |
スキーマ
使用上の注意
Key-Value マップの概要については、Key-Value マップの使い方をご覧ください。
Key-Value マップストアは、Key-Value ペアとしてデータ フォーマットのための軽量で永続的なメカニズムを提供します。実行時には、ポリシーやコードを通じて、これらにアクセスできます。マップには、key=value
の形式で任意のデータが含まれます。
たとえば、localhost=127.0.0.1
、zip_code=94110
、first_name=felix
などです。最初の例では、localhost
はキーで、127.0.0.1
は値です。各 Key-Value ペアは、Key-Value マップにエントリとして保存されます。Key-Value マップには多くのエントリを保存できます。
たとえば、さまざまなバックエンド環境に関連付けられた IP アドレスのリストを保存する必要があるとします。Key-Value ペアのリストがエントリとして含まれる ipAddresses
という Key-Value マップを作成できます。たとえば、この JSON はそのようなマップを表すことができます。
{ "entry" : [ { "name" : "Development", "value" : "65.87.18.18" }, { "name" : "Staging", "value" : "65.87.18.22" } ], "name" : "ipAddresses" }
この構造を使用して IP アドレスのストアを作成できます。これは、実行時にポリシーによって使用され、IP ホワイトリストまたは IP ブラックリストに、バックエンドのターゲット アドレスなどを動的に選択させます。通常、KeyValueMapOperations ポリシーは、複数のリクエスト / レスポンス トランザクションで再利用する必要がある長期間有効な情報を保存または取得するために使用されます。
Key-Value マップは、KeyValueMapOperations ポリシーを使用して、または Apigee Edge Management API を使用して直接操作できます。Organization Key-Value Maps API という API の詳細については、Management API リファレンスをご覧ください。たとえば、API を使用して、大規模なデータセットを Key-Value ストアにアップロードすることや、Key-Value マップエントリを管理するスクリプトを作成することが可能です。KeyValueMapOperations ポリシーでアクセスする前に、API で Key-Value マップを作成する必要があります。
キー名の指定と取得
<Parameter>
要素と <Value>
要素では、リテラル値(値は開始タグと終了タグの間にある)を指定するか、ref
属性を使用して、ランタイム時に値を使用する必要がある属性の名前を指定できます。
Parameter 要素は、作成されるキー名と、取得したり、削除したりするキー名を決定する特別な要素です。以下に 2 つの例を示します。 最初のものは文字通りキー名を指定し、2 番目のものは変数を使用してキー名を指定します。 KVM にキーを作成するために以下のものが使用されていると仮定しましょう。
<Parameter>key_name_literal</Parameter> <Parameter ref="key.name.variable"/>
最初の例では、"key_name_literal" のリテラル値がキー名として KVM に保存されます。2 番目のインスタンスでは、key.name.variable
の値が KVM のキーの名前になります。たとえば、key.name.variable
に値 foo
が含まれている場合、キーの名前は「foo」になります。
GET 操作でキーとキー値を取得する(または DELETE 操作で削除する)場合は、<Parameter> 設定が KVM のキー名と一致している必要があります。たとえば、KVM のキー名が「foo」の場合は、<Parameter>foo</Parameter>
でリテラル値を指定するか、<Parameter ref="variable.containing.foo"/>
のように正確な値「foo」が含まれる変数を指定できます。