KeyValueMapOperations ポリシー

概要

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

動画

KVM の詳細については、次の動画をご覧ください。

サンプル

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

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

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

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

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
   </Get>
</KeyValueMapOperations>

<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> タグに固有の属性を示します。

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

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

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

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 から複数のアイテムを取得できます。

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

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

KVM から複数の項目を取得する

次の例では、以下のキーと値を持つ KVM を想定しています。KVM は、最も人気のある映画のリストを常時保存することに加えて、すべての主要な映画の監督の名前を保存します。

現在最も人気のある映画と監督の名前を取得するために使用できる 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> 要素の属性を示します。

<Get assignTo="private.myvar">

<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> 要素の属性を示します。

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

属性

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

<Scope> 要素

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

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

<Scope>environment</Scope>

<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> 要素の属性を示します。

エラー リファレンス

Edge ポリシーから返されるエラーは、エラーコード参照で説明されている一貫した形式に従います。

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

ランタイム エラー

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

デプロイエラー

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

スキーマ

使用上の注意

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」が含まれる変数を指定できます。

関連トピック

• Organization key/value maps API