Key-Value マップの使用

このページの内容は Apigee と Apigee ハイブリッドに該当します。

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

このセクションでは、Key-Value マップ（KVM）の使用方法について説明します。

概要

有効期限がなく、API プロキシロジックにハードコードすべきでないデータについては、格納して実行時に取得されるようにすることが必要な場合があります。そのための方法としては、Key-Value マップ（KVM）が最適です。KVM は、暗号化された Key-Value の文字列ペアのカスタムコレクションです。

KVM にデータを保存する 3 つの一般的なユースケースを次に示します。

ユーザーセッションデータ: ランタイムでのみ作成および削除されるデータ。ランタイムの外部で、KVM エントリの表示や管理はできません。たとえば、ショッピングカートの内容などです。
構成（ルーティングルールやルックアップテーブルなど）: 通常はランタイムの外部で作成され、ランタイムによって読み取られるデータ。このデータは、UI または API を使用して構成され、変数または読み取り専用コンテンツとしてゲートウェイで使用できます。
たとえば、API プロキシのテスト環境で 1 つのターゲット URL（または Service Callout）を呼び出す必要があるとします。また、本番環境で別のターゲット URL を呼び出すこともできます。API プロキシで URL をハードコードするのではなく、それが含まれている環境を検出して、関連する KeyValueMapOperations ポリシーを実行し、適切な KVM から正しいターゲット URL を取得できます。

いずれかまたは両方のターゲットが変更された場合は、新しい URL で KVM を更新します。API プロキシによって新しい値が取得され、再デプロイは必要ありません。
認証情報: 外部サービスのトークン、OAuth トークンの生成に必要な認証情報、暗号化や Java コールアウトまたは JSON のウェブトークン（JWT）署名用 JavaScript で使用される秘密鍵などの認証情報、秘密鍵、トークンを保存します。認証情報、鍵、トークンは、リクエストで渡すかプロキシロジックにハードコードする代わりに、KVM に格納し、それらを必要とするターゲットが呼び出されたときに動的に取得されるようにできます。

Key-Value 文字列ペアを格納すると役立つ状況は他にもあります。一般に、次のような場合は KVM の使用を検討してください。

コード内の特定のブロックで、実行時に異なる値が必要になる場合。
機密データをハードコード以外の方法で渡す必要がある場合。
キャッシュのように有効期限のない値を格納する場合。

場合によっては、プロパティセットの方が使いやすくなるため、KVM の代わりに使用できます。詳細については、プロパティセットの使用をご覧ください。

KVM のスコープについて

スコープは、KVM が利用可能な範囲を定義します。KVM は次の各スコープで作成できます。

スコープ	説明
API プロキシ	KVM にアクセスできるのは API プロキシだけです。
環境	特定の環境内のすべての API プロキシが KVM にアクセスできます。たとえば、`prod` 環境にデプロイされた API プロキシは、`test` 環境の KVM にアクセスできないようにすることが可能です。同じ KVM キーを本番環境で使用できるようにするには、`prod` 環境をスコープとする並列 KVM を作成します。
組織	すべての環境のすべての API プロキシが KVM にアクセスできます。

KVM の暗号化について

Apigee では、API プロキシ、組織、環境のスコープのすべての KVM エントリが、Apigee 組織のプロビジョニング時に提供される Cloud KMS キーを使用して保護されます（組織リソースの runtimeDatabaseEncryptionKey フィールドを参照）。Apigee では、AES256 を暗号化標準として使用しています。

Apigee ハイブリッドでは、API プロキシ、組織、環境の、すべての KVM エントリに対して個別の暗号鍵を指定できます。Apigee では、暗号化標準として AES128、AES196、AES256 のいずれかの暗号サイズを使用できます。

KVM の作成

以下のセクションでは、KVM の作成について説明します。

Cloud コンソールの Apigee

新しい（空の）KVM を作成するか、KVM のリストを表示するには:

ブラウザで Cloud コンソールの Apigee UI を開きます。
左側のナビゲーションペインで、[管理] > [環境] の順にクリックします。
使用可能な環境のリストから、編集する環境を選択します。
[環境の詳細] ページの [Key Value Maps] タブをクリックします。
[Key Value Maps] ページに、既存の KVM のリストが表示されます。KVM をまだ作成していない場合、リストは空です。
新しい（空の）KVM を作成するには、[+ Create Key Value Map] をクリックします。
[Add key value map] ダイアログが表示されます。
[Key value map name] フィールドに KVM の名前を入力します。
名前には、英数字、ハイフンのみを使用でき、255 文字以下にする必要があります。スペースやその他の特殊文字は使用できません。例: my-kvm-1
[作成] をクリックします。
新しい KVM がリストに表示されます。

従来の Apigee UI

新しい（空の）KVM を作成するか、KVM のリストを表示するには:

Apigee UI にログインします。
[Admin] > [Environments] > [Key-Value Maps] を選択します。
[Environments] プルダウンリストから、KVM を作成する環境を選択します。
[Key Value Maps] ページに、既存の KVM のリストが表示されます。KVM をまだ作成していない場合、リストは空です。
新しい（空の）KVM を作成するには、[+Key Value Map] をクリックします。
[Add key value map] ダイアログが表示されます。
[Name] フィールドに KVM の名前を入力します。
名前に使用できるのは、文字、数字、ハイフンのみです。スペースやその他の特殊文字は使用できません。例: my-kvm-1
[Add] をクリックします。
新しい KVM がリストに表示されます。

Apigee API

Apigee API を使用して、次のスコープの KVM の作成、一覧取得、削除を行います。

KVM ポリシー

KVM をランタイムに作成し、API プロキシで更新するには、KeyValueMapOperations ポリシーを使用します。ポリシーでは、親要素の mapIdentifier 属性に KVM の名前を指定します。

<InitialEntries> 要素を使用すると、ポリシーを UI に保存するか、API プロキシをデプロイ（オフラインで開発した場合）するとすぐに、ベースラインエントリを新しい KVM に作成して入力できます。ポリシー内の値が変更された場合は、既存の値が上書きされます。新しい Key-Value は、既存の Key-Value とともに既存の KVM に追加されます。

<Put> 要素は、KVM がまだ存在しない場合には新たに作成し、1 つ以上の値を持つキーを作成します。KVM がすでに存在する場合は、Key-Value ペアが追加されます（キーがすでに存在する場合は更新されます）。KVM ポリシーでは複数の <Put> 要素を使用できます。

デバッグ

暗号化された KVM 値を取得するために KeyValueMapOperations ポリシーを使用する場合、値を保存する変数の名前を指定します。すべての KVM 値が暗号化されるため、変数名に private. 接頭辞を追加する必要があります。これにより、デバッグセッションに KVM Key-Value ペアが表示されなくなります。

KVM の取得

KeyValueMapOperations ポリシーの <Get> 要素を使用して KVM を取得します。すべての KVM 値は暗号化されるため、取得した値を格納する変数の名前に private. 接頭辞を追加します。この接頭辞を追加することで、API プロキシをデバッグする際のデバッグセッションで値が非公開になります。詳細については、<Get> 要素をご覧ください。

KVM の削除

以下のセクションでは、KVM の削除について説明します。