このページの内容は 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 の作成について説明します。
新しい(空の)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 がリストに表示されます。
新しい(空の)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 を使用して、次のスコープの 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 の削除について説明します。
KVM を削除するには:
- ブラウザで Cloud コンソールの Apigee UI を開きます。
- 左側のナビゲーション ペインで、[管理] > [環境] の順にクリックします。
- 使用可能な環境のリストから、編集する環境名を選択します。
- [環境の詳細] ページの [Key Value Maps] タブをクリックします。
[Key Value Maps] ページに、既存の KVM のリストが表示されます。
- 削除する KVM の行を見つけます。
- [操作] 列にある delete をクリックします。
- [Delete Key Value Map] ダイアログでこのオペレーションを確定します。
KVM が削除され、リストから除外されます。
KVM を削除するには:
- Apigee UI にログインします。
- [Admin] > [Environments] > [Key-Value Maps] を選択します。
- [Environments] プルダウン リストから、KVM を削除する環境を選択します。
[Key Value Maps] ページに、既存の KVM のリストが表示されます。
- 削除する KVM にカーソルを合わせます。
- [deleteDelete] をクリックします。
- [Delete] をクリックして削除操作を確定します。
KVM が削除され、リストから除外されます。
次のいずれかの Apigee API を使用して、スコープに基づいて KVM を削除します。