KeyValueMapOperations ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

What

Apigee で利用可能な Key-Value マップ（KVM）ストアへのポリシーベースのアクセス権を提供します。Key-Value ペアは、PUT オペレーション、GET オペレーション、または DELETE オペレーションを指定する KeyValueMapOperations ポリシーを構成することで、名前付きの既存のマップに保存、取得、削除できます（これらのオペレーションの少なくとも 1 つは、ポリシーによって実行する必要があります）。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

注: Apigee Hybrid バージョン 1.4.0 のリリース以降、Apigee はデフォルトですべての KVM を暗号化します。デバッグ（Debug）セッションで KVM 情報を非表示にするには、GET コマンドで KVM にアクセスするときにすべての変数で private. 属性を使用します。private. 属性が使用されていない場合でも、KVM は暗号化されています。ただし、KVM 情報はデバッグ（Debug）セッションで復号され、例外はスローされません。

動画: 次の動画で、KVM の概要を紹介します。

サンプル

リテラルで KVM を PUT

次のポリシーが実行されると、FooKVM という名前の暗号化された KVM が作成され、（変数から抽出された値で設定されていない）リテラル文字列 foo および bar で設定された 2 つの値を持つ FooKey_1 という名前のキーが作成されます。次の例でキーを GET するときは、必要な値を取得するためにインデックス番号を指定します。

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

スコープは environment です。つまり、管理 UI で [API] > [環境の構成] > [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 に動的にアクセス

次のポリシーでは、<MapName> 要素を使用して、フロー変数で KVM を動的に参照します。この要素は、フロー変数から KVM 識別子を取得します。なお、mapIdentifier 属性は省略されています。mapIdentifier は <MapName> 属性では使用できません。

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <MapName ref="flow.variable"/>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

変数で KVM を PUT

有用な KVM の簡単な例は、URL を短縮するサービスです。KVM は、短縮 URL と対応する完全な URL を格納するように構成できます。

このポリシー サンプルでは、KVM が作成されます。このポリシーは、PUT コマンドを使用して 2 つの関連する値を持つキーを urlMapper という名前の KVM に配置します。

<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

次の KVM とエントリは Apigee の Key-Value ストアで生成され、ポリシーを接続する API プロキシにスコープ設定されます。

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

このエントリは、削除するまで保持されます。Key-Value ストアのエントリは、クラウドを実行している Apigee のインスタンス間で分散されます。

変数から KVM を GET

有用な KVM の簡単な例は、URL を短縮するサービスです。KVM は、短縮 URL と対応する完全な URL を格納するように構成できます。

KeyValueMapOperations PUT タブでカバーされているような KVM エントリの値を取得するには、次のように KVM を GET するようにポリシーを構成します。

<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

デバッグ（Debug）セッションで KVM 情報を非表示にするには、GET コマンドで KVM にアクセスするときにすべての変数で private. 属性を使用します。private. 属性が使用されていない場合でも、KVM は暗号化されています。ただし、KVM 情報はデバッグ（Debug）セッションで復号され、例外はスローされません。

この例では、変数 private.encryptedVar が KVM の foo キーの復号された値を保持します。

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
  <Scope>apiproxy</Scope>
  <Get assignTo="private.encryptedVar" index='1'>
    <Key>
      <Parameter>foo</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

データが取得されたので、他のポリシーやコードは、その変数から値を抽出することによってそのデータにアクセスできます。

<KeyValueMapOperations>

Key-Value マップ（KVM）へのポリシーベースのアクセス権を提供します。

構文

<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>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
      <Value>VALUE_LITERAL</Value>
    </Entry>
  </InitialEntries>
  <Put override="BOOLEAN">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Put>
  <Get assignTo="VARIABLE_NAME" index="INDEX_NUMBER">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </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 属性は、オペレーションする KVM の名前を指定します。また、<MapName> 要素を使用して KVM を動的に指定することもできます。

属性	説明	デフォルト	プレゼンス
mapIdentifier	アクセスする KVM をポリシーに伝える識別子を指定します。 この識別子と <MapName> の両方が指定されていない場合、kvmap という名前の KVM が使用されます。<MapName> 要素を指定した場合、この属性は使用できません。	該当なし	省略可

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

属性	説明	デフォルト	要否
name	ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。 管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
continueOnError	ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。 ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について） 現在のフローにおける障害処理	false	省略可
enabled	ポリシーを適用するには、true に設定します。 ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
async	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>

デフォルト	なし この要素を省略した場合、ポリシーの name 属性の値が使用されます。
要否	省略可
タイプ	文字列

子要素

このセクションでは、KeyValueMapOperations ポリシーの要素と属性について説明します。

<Delete> 要素

指定された Key-Value ペアを削除します。<Get>、<Put>、<Delete> のうち、少なくとも 1 つを使用する必要があります。

KVM の名前は、ルート要素の mapIdentifier 属性か <MapName> 要素を使用して指定してください。次に例を示します。

<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>

デフォルト	該当なし
要否	<Get> または <Put> が存在しない場合は必須です。
型	該当なし

<Entry> 要素

KVM のシード値。この値は初期化時に KVM に代入されます。Apigee の場合、キーのサイズは 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 からキャッシュに保存された値を Apigee が更新するまでの期間を秒単位で指定します。

値が 0 または -1 の場合、もしくはこの要素を除外した場合、デフォルト値の 300 秒が使用されます。次に例を示します。

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

デフォルト	300 （5 分）
要否	省略可
タイプ	整数

KVM は、キーと値を NoSQL データベースに保存する、長期的な永続性メカニズムです。そのため、実行時に KVM からの読み取りを行うとプロキシのパフォーマンスが低下する可能性があります。パフォーマンスを向上させるため、Apigee には、実行時に KVM の Key-Value をキャッシュに保存するためのメカニズムが組み込まれています。この KVM オペレーション ポリシーは、GET オペレーションのため、常にキャッシュから読み取ります。

<ExpiryTimeInSecs> 要素を使用すると、ポリシーで使用される Key-Value を、KVM から再度更新するまでキャッシュに保存する期間を制御できます。ただし、GET オペレーションと PUT オペレーションではキャッシュの有効期限に与える影響にいくつかの違いがあります。

GET - KVM の GET オペレーションを初めて実行するときに、KVM（名前は、ポリシーのルート mapIdentifier 属性または <MapName> 要素で指定されます）からリクエストされた Key-Value がキャッシュに読み込まれ、次のいずれかが行われるまで後続の GET オペレーションのために保持されます。

• <ExpiryTimeInSecs> に指定された秒数後に期限切れになります。
  または
• KVM ポリシーの PUT オペレーションは、（次で説明される）既存の値を上書きします。

PUT - PUT オペレーションは、指定された KVM に Key-Value を書き込みます。キャッシュにすでに存在するキーに PUT で書き込みが行われると、そのキャッシュは直ちに更新され、ポリシーの <ExpiryTimeInSecs> 要素で指定された秒数の間、新しい値が保持されます。ただし、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 の値が取得されます。

注

• 最高のパフォーマンスを得るには、予想される API トラフィックの量とキャッシュの有効期限のバランスを調整します。たとえば、トラフィックが多い場合、データベースが頻繁に更新されないように、より長いキャッシュ有効期間を設定できます。
• KVM キャッシュを手動でリセットする方法はありません。ただし、短時間の <ExpiryTimeInSecs> を使用して 1 回限りの PUT オペレーションを実行する一時的なポリシーを作成できます。指定した秒数間 PUT オペレーションを行った値を含むキャッシュがリセットされます。
• Apigee UI または API を使用して KVM を更新しても、KVM キャッシュはリセットされません。
• 複数のオペレーションを同じポリシーで使用できます。その場合、そのポリシーにより各オペレーションが順番に実行されます。同じキーを使用して同じポリシーで PUT と GET を使用する場合、PUT は書き込み時に、キャッシュの有効期限を暗黙的にリセットします。

<Get> 要素

指定されたキーの値を取得します。<Get>、<Put>、<Delete> のうち、少なくとも 1 つを使用する必要があります。

Apigee は、KVM に格納されているデータをすべて暗号化します。詳細については、暗号鍵についてをご覧ください。<Get> を使用する場合、Apigee は保存されたデータを復号し、メッセージ コンテキストの変数に割り当てます。変数名は assignTo 属性を使用して指定します。

KVM の名前は、ルート要素の mapIdentifier 属性か <MapName> 要素のどちらかを使用して指定してください。

ポリシーに複数の Get ブロックを含めると、KVM から複数のアイテムを取得できます。

注: 複数のオペレーションを同じポリシーで使用できます。その場合、そのポリシーにより各オペレーションが順番に実行されます。同じキーを使用して同じポリシーで PUT と GET を使用する場合、PUT は書き込み時に、キャッシュの有効期限を暗黙的にリセットします。詳細については、ExpiryTimeInSecs 要素をご覧ください。

デフォルト	該当なし
要否	<Put> または <Delete> が存在しない場合は必須です。
型	なし

属性

次のテーブルに、<Get> 要素の属性を示します。

属性	説明	デフォルト	プレゼンス
assignTo	取得した値を割り当てる変数。	該当なし	必須
index	複数の値を持つキーから取得するアイテムのインデックス番号（1 から始まるインデックス）。たとえば、index=1 を指定すると、最初の値が返され、assignTo 変数に割り当てられます。インデックス値が指定されない場合、そのエントリのすべての値は java.util.List として変数に割り当てられます。 例については、サンプルの「Get Value from KVM」タブをご覧ください。	該当なし	省略可

KVM から単一項目を取得する

この例のステップ構成では、ポリシーは KVM 内の単一キーの値を読み取って復号し、復号された値を myvar という名前の変数に割り当てます。

<Get assignTo="myvar" index="1">
  <Key>
    <Parameter>key_name_literal</Parameter>
  </Key>
</Get>

デバッグ セッションから取得したデータの除外

KVM に機密データが保存されている場合もあります。取得したデータがデバッグ セッションに表示されないようにするには、assignTo 属性で指定された変数名に private. 接頭辞を使用します。private. 接頭辞を使用しない場合、KVM から取得したデータは、作成したデバッグ セッションにクリアテキストで表示されます。

この例のステップ構成では、ポリシーは KVM 内の単一のキーに関連付けられた値を読み取って復号し、その値を変数に割り当てます。割り当てはデバッグ セッションに表示されません。

<Get assignTo="private.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

top_movies キーに関連付けられた値には、複数の映画名がカンマ区切りで含まれています。

この構成例では、ポリシーは現在の人気の映画とその監督の名前を取得します。

<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 プロキシが呼び出されると、Apigee は対応する値を持つ次の変数を作成します。これらの変数は、後で API プロキシフローで使用できます。

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

最初の <Get> 要素の index 属性は 1 のため、top.movie.pick の値はカンマ区切りのリストの最初の項目を示しています。次に、2 番目の <Get> 要素は、top.movie.pick に割り当てられた値をキーとして使用し、movie.director に値を取得します。

<InitialEntries> 要素

KVM のシード値。この値は初期化時に KVM に代入されます。ルート要素では、必ず mapIdentifier 属性を使用して KVM の名前を指定してください。

注: <MapName> 要素が使用されている場合、<InitialEntries> は使用できません。

次に例を示します。

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

この要素を使用する場合、API プロキシのデプロイされたバージョンの Apigee UI にポリシーを保存する場合、または、この要素を備えるポリシーを含む API プロキシ バンドルをデプロイする場合、キーは自動的に KVM に作成されます。ポリシーの値が KVM の値と異なる場合、API プロキシのデプロイ時に KVM の値が上書きされます。新しい Key-Value は、既存の Key-Value とともに既存の KVM に追加されます。

この要素によって代入されるキーと値は、リテラルである必要があります。たとえば、<Parameter ref="request.queryparam.key"> はこの要素内ではサポートされていません。

キーサイズは 2 KB に制限されています。

デフォルト	該当なし
要否	省略可
型	該当なし

<Key> 要素

KVM エントリ内のキーを指定します。この要素は、<Get>、<Put>、または <Delete> の子要素として表示されます。あるいは、<InitialEntries> の子である <Entry> 要素の子として表示されます。固定キーの例を次に示します。

<Key>
  <Parameter>KEY_NAME_LITERAL</Parameter>
</Key>

キーは、動的要素を含む複合キーにすることもできます。つまり、複数の <Parameter> を追加してキーを作成できます。たとえば、変数 userID と role の内容を組み合わせて動的キーを作成できます。動的に決定される複合キーを指定するステップ構成の例を次に示します。

<Key>
  <Parameter ref='userID'/>
  <Parameter ref='role'/>
</Key>

キー名の設定方法に関する詳細については、<Parameter> 要素をご覧ください。

キーサイズは 2 KB に制限されています。

注: ratelimit という名前は予約されています。詳しくは、Apigee コミュニティのこちらの投稿をご覧ください。

デフォルト	該当なし
要否	省略可
型	該当なし

<MapName> 要素

<MapName> 要素を使用すると、実行時に動的に使用する KVM をポリシーで識別できます。KVM を動的に選択する機能により、ポリシーが実行されるコンテキストに応じて、異なる KVM にアクセスできる 1 つの KeyValueMapOperations ポリシーを柔軟に設計できます。

例:

<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>

最初の行で、KVM 名をリテラル文字列として指定します。2 行目で、フロー変数から名前を取得します。3 行目で、フロー変数が空の値になった場合は、代わりにリテラル文字列が使用されます。

ポリシーで <MapName> を使用する場合は、mapIdentifier 属性を指定しないでください。詳細については、ポリシーの属性をご覧ください。

プロキシがデプロイされたときにマップが存在しない場合、マップは作成されず、ポリシーの実行時に Apigee によってランタイム エラーがスローされます。フロー変数が指定されている場合、<InitialEntries> 要素は許可されません。デプロイ中に検証エラーが発生します。

<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 エントリを取得、更新、削除する場合でも、キー名を KVM 内のキーの名前と一致させる必要があります。ガイドラインのキー名の指定と取得をご覧ください。

デフォルト	該当なし
要否	必須
型	文字列

属性

次の表に、<Parameter> 要素の属性を示します。

属性	説明	デフォルト	要否
Ref	作成、取得、または削除するキーの正確な名前が値に含まれている変数の名前を指定します。	該当なし	開始タグと終了タグの間にリテラル値が指定されていない場合は必須です。

<Put> 要素

Key-Value ペアを KVM に書き込みます。ルート要素の mapIdentifier 属性で指定された KVM が存在せず、<MapName> 要素が使用されない場合、マップが自動的に作成されます。Key-Value マップがすでに存在する場合は、Key-Value がそのマップに追加されます。

UI または API を使用して KVM を作成するには、次のリンク先をご覧ください。

• Apigee UI で KVM を使用して、UI で暗号化された環境スコープ KVM を作成する
• 組織を対象とした Key-Value マップ API
• 環境を対象とした Key-Value マップ API
• API プロキシを対象とした Key-Value マップ API

注: 複数のオペレーションを同じポリシーで使用できます。その場合、そのポリシーにより各オペレーションが順番に実行されます。同じキーを使用して同じポリシーで PUT と GET を使用する場合、PUT は書き込み時に、キャッシュの有効期限を暗黙的にリセットします。詳細については、ExpiryTimeInSecs 要素をご覧ください。

キーサイズは 2 KB に制限されています。

<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>

デフォルト	該当なし
要否	<Get> または <Delete> が存在しない場合は必須です。
型	該当なし

警告: ポリシーで PUT コマンドが使用され、null キーで Key-Value が KVM に配置される場合、次のキーが自動的に作成されます。__$$_EDGE_KVM_EMPTY_KEY_$$__

このような状況は、たとえば、変数を参照してキーを代入するとき、参照される変数が null の場合に発生します。null キーを持つ新しい PUT が試行されると、そのキーだけが使用されるため、そのキーの既存の値はポリシーが実行されるたびに上書きされる可能性があります。

属性

次の表に、<Put> 要素の属性を示します。

属性	説明	デフォルト	要否
オーバーライド	true に設定すると、キーの値がオーバーライドされます。 <Put override="false"> は、そのキーの KVM ストアに現在エントリが保持されていない場合にのみ書き込まれます。	true	省略可

<Scope> 要素

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

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

<Scope>environment</Scope>

デフォルト	environment
要否	省略可
タイプ	文字列
有効な値	organization environment apiproxy policy（API プロキシ リビジョン）

複数のプロキシで同じ KVM を使用する必要がある場合は、KVM ポリシーを SharedFlow に追加し、プロキシで SharedFlow を使用することを検討してください。

<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 を含む値を持つ変数の名前を指定します。	該当なし	開始タグと終了タグの間にリテラル値が指定されていない場合は必須です。リテラル値が指定されている場合は禁止されます。

エラー リファレンス

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

ランタイム エラー

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

ヒント: エラーの解決にサポートが必要な場合は、「修正」列の をクリックして、詳しいトラブルシューティング情報をご覧ください。

障害コード	HTTP ステータス	原因	修正
steps.keyvaluemapoperations.UnsupportedOperationException	500	このエラーは、KeyValueMapOperations ポリシーで mapIdentifier 属性が空の文字列に設定されている場合に発生します。

デプロイエラー

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

ヒント: エラーの解決にサポートが必要な場合は、「修正」列の をクリックして、詳しいトラブルシューティング情報をご覧ください。

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

スキーマ

サンプル: 最新のスキーマについては、GitHub リポジトリのサンプルをご覧ください。

使用上の注意

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

Apigee UI を使用すると、Apigee UI での KVM の使用で説明しているとおり、環境スコープでのみ KVM を定義できます。Apigee API を使用すると、次のセクションで説明するとおり、組織、環境、API プロキシをスコープとした KVM を定義できます。

• 組織を対象とした Key-Value マップ API
• 環境を対象とした Key-Value マップ API
• API プロキシを対象とした Key-Value マップ API

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

注: キーのサイズは 2 KB に制限されています。

たとえば、localhost=127.0.0.1、zip_code=94110、first_name=felix です。最初の例では、localhost はキーで、127.0.0.1 は値です。各 Key-Value ペアは、Key-Value マップにエントリとして保存されます。KVM には多数のエントリを格納できます。

たとえば、さまざまなバックエンド環境に関連付けられた IP アドレスのリストを格納する必要があるとします。エントリとして Key-Value ペアのリストが含まれる ipAddresses という KVM を作成するとします。たとえば、次の JSON はこのようなマップを表すことができます。

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

この構造を使用して IP アドレスのストアを作成できます。これは、実行時にポリシーによって使用され、IP 許可リストまたは IP 拒否リストに、バックエンドのターゲット アドレスなどを動的に選択させます。通常、KeyValueMapOperations ポリシーは、複数のリクエスト / レスポンス トランザクションで再利用する必要がある長期間有効な情報を保存または取得するために使用されます。

KVM は、KeyValueMapOperations ポリシーによって、または Apigee API を介して直接オペレーションできます。たとえば、API を使用して、大規模なデータセットを Key-Value ストアにアップロードすることや、Key-Value マップエントリを管理するスクリプトを作成することが可能です。KeyValueMapOperations ポリシーでアクセスする前に、API で KVM を作成する必要があります。

キー名の指定と取得

<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 のキー名が my_key の場合、<Parameter>my_key</Parameter> でリテラル値を指定するか、正確な値 mny_key を含む変数を指定します。（例: <Parameter ref="variable.containing.foo"/>）。

注: ratelimit という名前は予約されています。詳細については、Quota Policy - Throws NullPointerException をご覧ください。

関連トピック

KVM の詳細については、次のトピックをご覧ください。

• Key-Value マップの使用
• 組織を対象とした Key-Value マップ API
• 環境を対象とした Key-Value マップ API
• API プロキシを対象とした Key-Value マップ API