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 は、organization、environment、apiproxy の各スコープで作成できます。

たとえば、KVM でデータを必要とする API プロキシが 1 つのみの場合は、その API プロキシのみがデータにアクセスできる apiproxy スコープで KVM を作成できます。

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

すべての環境のすべてのプロキシが同じ KVM にアクセスするようにするには、organization スコープで KVM を作成します。

暗号化された KVM の概要

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

Edge では、暗号化された値の表示処理に次の方法が使用されます（暗号化された KVM の作成については、KVM の管理と使用をご覧ください）。

Edge UI

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

Management API

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

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

トレースとデバッグ

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

KVM の管理と使用

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

KVM の作成と更新

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

  • Key-Value Map Operations ポリシー（暗号化なし）

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

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

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

  • Management API

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

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

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

  • 管理 UI

    Edge 管理 UI では、UI に表示される KVM の唯一のスコープである環境スコープの KVM を作成して更新できます。管理 UI は、実行時に API プロキシの KVM データを手動で管理するのに適しています。 詳細については、環境 Key-Value マップの作成と編集をご覧ください。

KVM の取得

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

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

KVM の例

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