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>
    

スコープは「環境」です。つまり、[APIs] > [Environment Configuration] > [Key Value Maps] の管理 UI で 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 マップ管理 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 で作成されたマップにアクセスするときに使用する識別子を指定します。

Core Persistence Services(CPS)を有効にしている組織では、KVM 名は、大文字と小文字が区別されます。たとえば、foobarFooBar は異なります。

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

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

なし 省略可

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

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

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

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

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

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

false 省略可
enabled

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

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

true 省略可
async

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

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

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

Key-Value マップのシード値。この値は、初期化時に Key-Value マップに代入されます。

Core Persistence Services(CPS)を有効にしている組織では、キーのサイズが 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 オペレーション ポリシーは、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 マップ管理 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"> はこの要素内ではサポートされていません。

Core Persistence Services(CPS)を有効にしている組織では、キーのサイズが 2 KB に制限されます。詳細については、Core Persistence Services(CPS)についてをご覧ください。

暗号化された Key-Value マップを作成するには、Key/Value Maps management API を使用します。

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

<Key> 要素

Key-Value マップエントリでキーを指定します。キーはコンポジットにできます。つまり、複数のパラメータを追加してキーを作成できます。たとえば、userIDrole を組み合わせて key を作成できます。次に例を示します。

    <Key>
        <Parameter>key_name_literal</Parameter>
    </Key>
    

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

Core Persistence Services(CPS)を有効にしている組織では、キーのサイズが 2 KB に制限されます。詳細については、Core Persistence Services(CPS)についてをご覧ください。

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

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

デフォルト なし
要否 必須
String

属性

次の表に、<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 つのキーが追加されています。

  • キー k1 と値 v1,v2
  • キー k2 と値 v3,v4
    <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 であると仮定しましょう。

  • キー foo_org と値 bar,test
    <Put>
        <Key>
            <Parameter ref="organization.name"/>
        </Key>
        <Value ref="apiproxy.name"/>
        <Value ref="environment.name"/>
    </Put>
    
デフォルト なし
要否 必須
String

属性

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

属性 説明 デフォルト 要否
ref 設定する Key-Value を含む値を持つ変数の名前を指定します。 なし 開始タグと終了タグの間にリテラル値が指定されていない場合は必須です。リテラル値が指定されている場合は禁止されます。

エラー リファレンス

Edge ポリシーから返されるエラーは、ポリシーエラー リファレンスで説明されている一貫した形式に従います。

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

ランタイム エラー

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

障害コード HTTP ステータス 原因 修正
steps.keyvaluemapoperations.SetVariableFailed 500

このエラーは、暗号化された Key-Value マップから値を取得し、その値を、名前に接頭辞 private のない変数に設定しようとすると発生します。この接頭辞はデバッグ時の基本的なセキュリティを確保するために必要であり、この接頭辞を付けておくと、暗号化された値が API プロキシのトレース セッションとデバッグ セッション時に非表示になります。

build
steps.keyvaluemapoperations.UnsupportedOperationException 500

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

build

デプロイエラー

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

エラー名 原因 修正
InvalidIndex Key Value Map Operations ポリシーの <Get> 要素で指定された index 属性がゼロまたは負の数である場合、API プロキシのデプロイは失敗します。インデックスは 1 から始まるため、ゼロまたは負の整数のインデックスは無効と見なされます。 build
KeyIsMissing このエラーは、Key Value Map Operations ポリシーの <InitialEntries> 要素の <Entry> の下で、<Key> 要素が完全に欠落しているか、<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.1zip_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 管理 API を介して直接操作することもできます。組織 Key-Value マップ API の詳細については、管理 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> に指定するか、正確な値 "foo" を含む、<Parameter ref="variable.containing.foo"/> のような変数を指定することができます。

関連トピック