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 トークンを生成するために必要な認証情報、JavaCallout ポリシーや JavaScript で暗号化や JSON Web Token（JWT）の署名に使う秘密鍵などの認証情報、秘密鍵、トークンを保存します。認証情報、鍵、トークンは、リクエストで渡すかプロキシ ロジックにハードコードする代わりに、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 のマスキングをオンまたはオフにするには、UI の [Mask values] 設定を使用するか、API リクエストで maskedValues フラグを使用します。

値は KVM レベルでマスクされます。KVM エントリを個別にマスクすることはできません。KVM 内のすべての値がマスクされるか、マスクされないかのいずれかになります。

注: 既存の KMV の場合、KVM のマスキングは自動的に有効になりません。KVM のマスキングを使用するには、既存の KVM を明示的に更新する必要があります。

KVM を作成する

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

Cloud コンソールの Apigee

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

  1. Google Cloud コンソールで、[管理] > [環境] ページに移動します。

    [環境] に移動

  2. 使用可能な環境のリストから、編集する環境を選択します。
  3. [環境の詳細] ページの [Key value maps] タブをクリックします。

    [Key value maps] ページに、既存の KVM のリストが表示されます。KVM をまだ作成していない場合、リストは空です。

  4. 新しい（空の）KVM を作成するには、[+ Create Key value maps] をクリックします。

    [Create key value map] ダイアログが表示されます。

  5. [Key value map name] フィールドに KVM の名前を入力します。

    名前には、英数字、ハイフンのみを使用でき、255 文字以下にする必要があります。スペースやその他の特殊文字は使用できません。例: my-kvm-1

  6. [Mask values] をクリックして、すべての値をマスクします。選択しない場合、KVM 値は書式なしテキストで表示されます。詳細については、KVM のマスキングについてをご覧ください。
  7. [作成] をクリックします。

    新しい 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 を取得する

Apigee API を使用して、次のスコープの KVM を取得します。

たとえば、API プロキシ スコープの KVM を取得するには、次の URL に GET リクエストを入力します。

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

KVM を更新する

Apigee API を使用して、次のスコープの KVM を更新します。

たとえば、API プロキシ スコープの KVM を取得するには、次の URL に GET リクエストを入力します。

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

KVM の値を管理する

以降のセクションで説明するように、API または KeyValueMapOperations ポリシーを使用して KVM の値を管理できます。

API を使用して KVM の値を管理する

Apigee API を使用して、次のスコープの KVM の値を管理します。

KeyValueMapOperations ポリシーを使用して KVM の値を管理する

KeyValueMapOperations ポリシーを使用して、KVM の値を追加、取得、削除します。

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

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

KeyValueMapOperations ポリシーの <Delete> 要素を使用して KVM 値を削除します。詳細については、<Delete> 要素をご覧ください。

KVM を削除する

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

Cloud コンソールの Apigee

KVM を削除するには:

  1. Google Cloud コンソールで、[管理] > [環境] ページに移動します。

    [環境] に移動

  2. 使用可能な環境のリストから、編集する環境名を選択します。
  3. [環境の詳細] ページの [Key value maps] タブをクリックします。

    [Key value maps] ページに、既存の KVM のリストが表示されます。

  4. 削除する KVM の行を見つけます。
  5. [操作] 列にある をクリックします。
  6. [Delete Key Value Map] ダイアログでこのオペレーションを確定します。

    KVM が削除され、リストから除外されます。

従来の Apigee UI

KVM を削除するには:

  1. Apigee UI にログインします。
  2. [Admin] > [Environments] > [Key-Value Maps] を選択します。
  3. [Environments] プルダウン リストから、KVM を削除する環境を選択します。

    [Key Value Maps] ページに、既存の KVM のリストが表示されます。

  4. 削除する KVM にカーソルを合わせます。
  5. [Delete] をクリックします。
  6. [Delete] をクリックして削除操作を確定します。

    KVM が削除され、リストから除外されます。

Apigee API

次のいずれかの Apigee API を使用して、スコープに基づいて KVM を削除します。