KeyValueMapOperations ポリシー

Edge UI からの Key Value Map Operations アイコン

概要

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 名で大文字と小文字が区別されます。たとえば、foobarFooBar とは異なります。

この属性を除外すると、kvmap という名前の KVM が使用されます。

組織 / 環境 / API プロキシのスコープ内で、mapIdentifier 属性を使用して独自のマップ名を指定できます。

なし 省略可

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

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

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

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

なし 必須
continueOnError

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

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

false 任意
enabled

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

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

true 任意
async

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

false 非推奨

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

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

なし

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

要否 任意
種類 文字列

<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 のキャッシュ保存

  1. GET 操作は、値「10」をキャッシュに追加する「rating」の値を取得します。ポリシーに対する <ExpiryTimeInSecs> は 60 です。
  2. 30 秒後、GET ポリシーが再度実行され、キャッシュから「10」が取得されます。
  3. 5 秒後、PUT ポリシーは「rating」の値を「8」に更新し、PUT ポリシーに対する <ExpiryTimeInSecs> は 20 になります。キャッシュはすぐに新しい値で更新され、20 秒間キャッシュに残るように設定されます(PUT が実行されなかった場合、最初の GET によって最初に代入されたキャッシュは、元の 60 秒の残りの 30 秒間さらに存在します)。
  4. 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 名を「private.」で開始します。次に例を示します。


<Get assignTo="private.myvar">

接頭辞を使用せずに暗号化された Key-Value マップを取得しようとすると、ポリシーはエラーを返します。この接頭辞はデバッグ時の基本的なセキュリティのために必要であり、API プロキシ トレースおよびデバッグ セッションで暗号化された値をマスクします。

暗号化された Key-Value マップの作成については、Key-Value Maps management API環境 Key-Value マップの作成と編集の「作成」トピックをご覧ください。

なし 必須
index

複数の値を持つキーからフェッチする項目のインデックス番号(1 ベースのインデックス)。たとえば、index=1 を指定すると、最初の値が返され、assignTo 変数に割り当てられます。インデックス値が指定されない場合、そのエントリのすべての値は、java.util.List として変数に割り当てられます。

例については、サンプルの「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 マップエントリでキーを指定します。キーはコンポジットにできます。つまり、複数のパラメータを追加してキーを作成できます。たとえば、userIDrole を組み合わせて 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

true に設定すると、キーの値がオーバーライドされます。

false 省略可

<Scope> 要素

Key-Value マップのアクセシビリティの境界線を定義します。デフォルトのスコープは environment です。つまり、デフォルトでは、マップエントリは、(テストやプロッドなどの)環境内で実行されているすべての API プロキシによって共有されます。スコープを apiproxy に設定すると、値をマップに書き込む API プロキシによってのみ Key-Value マップのエントリにアクセスできます。

マップまたはマップエントリにアクセスするときは、マップの作成時に使用したものと同じスコープ値を指定する必要があります。たとえば、マップが apiproxy スコープで作成された場合は、その値を取得したり、変更を加えたり、エントリを削除したりするには、apiproxy スコープを使用する必要があります。

<Scope>environment</Scope>
デフォルト environment
要否 省略可
文字列
有効な値:
  • organization
  • environment
  • apiproxy
  • policy(API プロキシ リビジョン)

<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 マップから値を取得し、名前に接頭辞 private がない変数に値を設定しようとすると発生します。デバッグ時の基本的なセキュリティのために必須なこの接頭辞により、API プロキシ Trace およびデバッグ セッションで、暗号化された値は表示されません。

steps.keyvaluemapoperations.UnsupportedOperationException 500

このエラーは、mapIdentifier 属性が Key Value Map Operations ポリシーで空の文字列に設定されている場合に発生します。

デプロイエラー

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

エラー名 原因 解決方法
InvalidIndex Key Value Map Operations ポリシーの <Get> 要素に指定された index 属性がゼロまたは負の数である場合、API プロキシのデプロイは失敗します。インデックスは 1 から始まるため、ゼロまたは負の整数のインデックスは無効と見なされます。
KeyIsMissing このエラーは、<Key> 要素が完全に欠落しているか、Key Value Map Operations ポリシーの <InitialEntries> 要素の <Entry> の下の <Key> 要素に <Parameter> 要素がない場合に発生します。
ValueIsMissing このエラーは、Key Value Map Operations ポリシーの <InitialEntries> 要素の <Entry> 要素の下に <Value> 要素がない場合に発生します。

スキーマ

使用上の注意

Key-Value マップの概要については、Key-Value マップの使い方をご覧ください。

Key-Value マップストアは、Key-Value ペアとしてデータ フォーマットのための軽量で永続的なメカニズムを提供します。実行時には、ポリシーやコードを通じて、これらにアクセスできます。マップには、key=value の形式で任意のデータが含まれます。

たとえば、localhost=127.0.0.1zip_code=94110first_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」が含まれる変数を指定できます。

関連トピック