Key-Value マップの使い方

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

その他のタイプの永続性については、キャッシュと永続性の追加をご覧ください。

KVM のシナリオ

ここでは、KVM が役立つ状況をいくつか紹介します。

  • 1 つの API プロキシを使用して、テスト環境で 1 つのターゲット(またはサービス コールアウト)URL を呼び出し、本番環境で別のターゲット URL を呼び出す必要がある場合があります。プロキシに URL をハードコードする代わりに、該当する URL がどの環境に含まれているかをプロキシに検出させ、次に、関連する Key-Value Map Operations ポリシーを実行することで、作成した KVM のいずれから正しいターゲット URL を取得させることができます。それ以降、ターゲットの一方または両方が変更されても、新しい URL で KVM を更新するだけで済みます。プロキシでは新しい値が取得されるため、プロキシを再デプロイする必要はありません。
  • 認証情報、秘密鍵、トークンについては格納することが推奨されます。たとえば、外部サービス用のトークン、OAuth トークンを生成するために必要な認証情報、Java コールアウトまたは JavaScript で暗号化に使用される秘密鍵、JSON ウェブトークン(JWT)の署名などです。認証情報、鍵、トークンは、リクエストで渡したり、プロキシ ロジックにハードコードしたりする代わりに、KVM に格納(常時暗号化)し、それらを必要とするターゲットが呼び出されたときに動的に取得されるようにできます。

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

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

KVM のスコープ

スコープとは、「KVM が使用可能な範囲」を意味します。KVM は、organizationenvironmentapiproxy のスコープで作成できます。

たとえば、KVM のデータを必要とする API プロキシが 1 つしかない場合は、apiproxy スコープで KVM を作成できます。この場合、該当する API プロキシしかデータにアクセスできません。

または、テスト環境のすべての API プロキシに Key-Value マップへのアクセスを許可する必要がある場合は、environment スコープで Key-Value マップを作成することになります。「prod」環境にデプロイされたプロキシは、「test」環境をスコープとした KVM にはアクセスできません。本番環境でも同じ KVM キーを使用できるようにするには、スコープを「prod」環境とした並列 KVM を作成します。

すべての環境のすべてのプロキシに同じ KVM へのアクセスを許可する場合は、organization スコープで KVM を作成します。

暗号化された KVM の概要

KVM の暗号化には Apigee によって生成される AES-128 暗号鍵が使用されます。KVM の暗号化に使用される鍵は、KVM のスコープで格納されます。たとえば、組織内で environment スコープを使用して作成する KVM の暗号化には、同じ環境をスコープとした鍵が使用されます。

Edge では、暗号化された値の表示処理に次の方法が使用されます(暗号化された KVM の作成方法の詳細については、KVM の管理および使用をご覧ください)。

Edge UI

暗号化された Key-Value マップの値は、アスタリスクでマスクされて UI に表示されます(*****)。次に例を示します。

管理 API

管理 API では、暗号化された値はマスクされた状態で返されます。暗号化された KVM を要求する Get 呼び出しに対する管理 API のレスポンスの例を次に示します。

    {
      "encrypted": true,
      "entry": [
        {
          "name": "Key1",
          "value": "*****"
        },
        {
          "name": "Key2",
          "value": "*****"
        }
      ],
      "name": "secretMap"
    }
    

トレースとデバッグ

Key-Value Map Operations ポリシーを使用して、暗号化された KVM 値を取得する場合は、値を格納する変数の名前を指定します。暗号化された値を取得するには、変数名に接頭辞「private.」を追加して、トレースおよびデバッグ セッションで KVM の Key-Value が非公開になるようにする必要があります。

KVM の管理および使用

KVM は、さまざまな方法で作成、管理、使用できます。このセクションでは、暗号化された KVM および暗号化されていない KVM の両方を作成および取得する際に使用できる各種オプションについて説明します。

KVM の作成および更新

KVM は、次の方法で作成および更新できます。

  • Key-Value Map Operations ポリシー(暗号化なし)

    API プロキシで実行時に KVM を作成および更新するには、Key-Value Map Operations ポリシーを使用します(ポリシーでは、親要素の mapIdentifier 属性に KVM の名前を指定します)。

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

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

  • 管理 API

    管理 API は、API プロキシでの実行時の操作に使用するものではなく、管理者が KVM を操作するためのものです。たとえば、管理 API を使用してテスト環境で KVM を削除および再作成する内部スクリプトを準備したり、すべてのプロキシが KVM から取得するキーの値をリセットしたりできます(KVM を実行時に操作するには、プロキシで Key-Value Map Operations ポリシーを使用します)。

    Key/Value Maps management API を使用すると、スコープ(organization、environment、apiproxy)を問わず、暗号化された KVM と Key-Value を作成、更新、削除できます。

    暗号化された KVM を管理 API で作成するには、JSON ペイロードに "encrypted" : "true" を追加します。KVM は、その作成時にのみ暗号化できます。既存の KVM を暗号化することはできません。

  • 管理 UI

    Edge 管理 UI では、environment スコープの KVM を削除および更新できます。environment スコープ以外の KVM は UI に表示されません。管理 UI は、API プロキシで実行時に KVM データを手動管理するのに役立ちます。詳細については、環境 Key-Value マップの作成と編集をご覧ください。

KVM の取得

暗号化された Key-Value マップと暗号化されていない Key-Value マップの取得方法は基本的に同じですが、Key-Value Map Operations ポリシーを使用する場合に限り、1 つわずかな違いがあります。

  • ポリシー: KVM を取得する場合は、それが暗号化されているかどうかにかかわらず、Key-Value Map Operations ポリシー<Get> 要素を使用します。1 つのわずかな違いは、暗号化された値を取得する場合は、取得された値を格納する変数の名前に「private.」という接頭辞を追加する必要があることです(詳細については、関連するトピックの Get 操作のセクションをご覧ください)。この接頭辞を追加することで、API プロキシをデバッグする際のトレースおよびデバッグ セッションで値が非公開になります。
  • Node.js: Node.js を使用して API プロキシを開発している場合は、apigee-access モジュールの KVM 取得関数を使用します。これらの関数は、KVM が暗号化されているかどうかにかかわらず、同等に使用できます。詳細については、Node.js で Key-Value マップにアクセスするをご覧ください。
  • 管理 API: 管理目的で、環境 Key-Value マップの作成と編集に従って KVM と Key-Value を取得できます。たとえば、JSON 定義を取得および格納することによって KVM をバックアップする場合は、管理 API を使用します。ただし、暗号化された値は API レスポンスで ***** として表示されることに留意してください。
  • 管理 UI: 管理 UI で environment スコープの KVM を表示するには、[APIs] > [Environment Configuration] > [Key Value Maps](従来の Edge)または [Admin] > [Environments] > [Key Value Maps](新しい Edge)に移動します。

KVM の例

KVM を使用して URL に値を挿入する方法の例については、https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html をご覧ください。