Azure API Management ポリシーで名前付きの値を使用する

API Management ポリシーはシステムの強力な機能の 1 つで、これを使用することにより、発行者は構成を通じて API の動作を変更できます。 API の要求または応答に対して順に実行される一連のステートメントが集まってポリシーが形成されます。 ポリシー ステートメントは、リテラル テキストの値、ポリシーの式、名前付きの値を使用して構築できます。

"名前付きの値" は、各 API Management インスタンス内にある名前と値ペアのグローバル コレクションです。 コレクション内の項目の数に制限はありません。 名前付きの値を使用すると、すべての API の構成とポリシーで定数文字列の値とシークレットを管理できます。

Azure portal 内の名前付きの値

値型

Type Description
普通紙 リテラル文字列またはポリシー式
Secret API Management によって暗号化されるリテラル文字列またはポリシー式
Key vault Azure Key Vault に格納されているシークレットの識別子。

プレーンテキストの値またはシークレットにはポリシー式を含めることができます。 たとえば、式 @(DateTime.Now.ToString()) では、現在の日付と時刻を含む文字列が返されます。

名前付きの値の属性の詳細については、API Management の REST API リファレンスのページを参照してください。

キー コンテナーのシークレット

シークレットの値は、API Management 内に暗号化された文字列 (カスタム シークレット) として、または Azure Key Vault 内のシークレットを参照することによって格納できます。

API Management のセキュリティ向上に役立つため、キー コンテナーのシークレットを使用することをお勧めします。

  • キー コンテナーに格納されているシークレットは、サービス間で再利用できます
  • きめ細かいアクセス ポリシーをシークレットに適用できます
  • キー コンテナーで更新されたシークレットは、API Management で自動的にローテーションされます。 キー コンテナー内で更新が行われると、4 時間以内に API Management 内の名前付きの値が更新されます。 また、Azure portal または管理 REST API を使用して、シークレットを手動で更新することもできます。

キー コンテナー統合の前提条件

  1. キー コンテナーを作成する手順については、「クイックスタート: Azure portal を使用してキー コンテナーを作成する」を参照してください。
  2. API Management インスタンスで、システムによって割り当てられた、またはユーザーが割り当てたマネージド ID を有効にします。
  3. コンテナーからシークレットを取得して一覧表示するアクセス許可を持つマネージド ID に、キー コンテナー アクセス ポリシーを割り当てます。 ポリシーを追加するには、次の手順を実行します。
    1. ポータルで、キー コンテナーに移動します。
    2. [設定] > [アクセス ポリシー] > [+ アクセス ポリシーの追加] を選択します。
    3. [シークレットのアクセス許可] を選択し、次に [Get](取得)[List](一覧表示) を選択します。
    4. [プリンシパルの選択] で、マネージド ID のリソース名を選択します。 システムによって割り当てられた ID を使用している場合、プリンシパルは API Management インスタンスの名前です。
  4. シークレットを作成するか、キー コンテナーにインポートします。 「クイック スタート:Azure portal を使用して Azure Key Vault との間でシークレットの設定と取得を行う」をご覧ください。

キー コンテナーのシークレットを使用するには、名前付きの値を追加または編集し、キー コンテナー の種類を指定します。 キー コンテナーからシークレットを選択します。

Key Vault ファイアウォールの要件

キー コンテナーで Key Vault ファイアウォールが有効になっている場合、追加要件は次のとおりです。

  • キー コンテナーにアクセスするには、API Management インスタンスの システムによって割り当てられた マネージド ID を使用する必要があります。
  • Key Vault ファイアウォールで、 [Allow Trusted Microsoft Services to bypass this firewall](信頼された Microsoft サービスがこのファイアウォールをバイパスすることを許可する) オプションを有効にします。

仮想ネットワークの要件

API Management インスタンスが仮想ネットワークにデプロイされている場合は、次のネットワーク設定も構成してください。

  • API Management サブネットで Azure Key Vault へのサービス エンドポイントを有効にします。
  • AzureKeyVault と AzureActiveDirectory のサービス タグへの送信トラフィックを許可するネットワーク セキュリティ グループ (NSG) 規則を構成します。

詳細については、仮想ネットワークへの接続に関するページに含まれているネットワーク構成の詳細を参照してください。

名前付きの値を追加または編集する

キー コンテナーのシークレットを追加する

キー コンテナー統合の前提条件」を参照してください。

注意事項

API Management でキー コンテナーのシークレットを使用する場合は、シークレット、キー コンテナー、またはキー コンテナーにアクセスするために使用するマネージド ID を削除しないように注意してください。

  1. Azure portal で、API Management インスタンスに移動します。

  2. [API] で、 [名前付きの値] > [+追加] を選択します。

  3. [名前] 識別子を入力し、ポリシー内でプロパティを参照するために使用される [表示名] を入力します。

  4. [値の種類] で、 [キー コンテナー] を選択します。

  5. キー コンテナーのシークレットの識別子 (バージョンなし) を入力するか、 [選択] を選択し、キー コンテナーからシークレットを選択します。

    重要

    キー コンテナーのシークレット識別子を自分で入力する場合は、バージョン情報が含まれていないことを確認してください。 そうしないと、キー コンテナーで更新が行われた後にシークレットが API Management で自動的にローテーションされません。

  6. [クライアント ID] で、システムによって割り当てられた、または既存のユーザー割り当てのマネージド ID を選択します。 API Management サービスでのマネージド ID の追加または変更方法については、こちらを参照してください

    注意

    ID には、キー コンテナーからシークレットを取得および一覧表示するためのアクセス許可が必要です。 キー コンテナーへのアクセスをまだ構成していない場合は、必要なアクセス許可を使用して ID を自動的に構成できるように、API Management によってプロンプトが表示されます。

  7. 名前付きの値を整理するのに役立つ 1 つ以上の省略可能なタグを追加して、保存 します。

  8. [作成] を選択します

    キー コンテナーのシークレットの値を追加する

プレーンまたはシークレットの値を追加する

  1. Azure portal で、API Management インスタンスに移動します。
  2. [API] で、 [名前付きの値] > [+追加] を選択します。
  3. [名前] 識別子を入力し、ポリシー内でプロパティを参照するために使用される [表示名] を入力します。
  4. [値の種類] で、 [プレーン] または [シークレット] を選択します。
  5. [値] に、文字列またはポリシー式を入力します。
  6. 名前付きの値を整理するのに役立つ 1 つ以上の省略可能なタグを追加して、保存 します。
  7. [作成] を選択します

名前付きの値が作成されたら、名前を選択して編集できます。 表示名を変更すると、その名前付きの値を参照するすべてのポリシーが、その新しい表示名を使用するように自動的に更新されます。

名前付きの値を使用する

このセクションの例では、次の表に示す名前付きの値が使用されます。

名前 Secret
ContosoHeader TrackingId
ContosoHeaderValue •••••••••••••••••••••• True
ExpressionProperty @(DateTime.Now.ToString())

ポリシーで名前付きの値を使用するには、{{ContosoHeader}} のように、二重の中括弧でその表示名を囲みます。次に例を示します。

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

この例では、ContosoHeaderset-header ポリシーのヘッダー名として使用されており、ContosoHeaderValue はそのヘッダーの値として使用されています。 このポリシーが API Management ゲートウェイの要求または応答で評価されるとき、{{ContosoHeader}}{{ContosoHeaderValue}} はそれぞれの値で置換されます。

名前付きの値は前の例のように完全な属性または要素値として使用できますが、次の例に示すように、リテラル テキスト表現に挿入するか、その一部と組み合わせることもできます:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

名前付きの値にはポリシー式を含めることもできます。 次の例では、ExpressionProperty 式が使用されています。

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

このポリシーが評価されるとき、{{ExpressionProperty}} はその値 @(DateTime.Now.ToString()) に置き換えられます。 値がポリシー式であるため、式が評価され、ポリシーがその実行に進みます。

これは、名前付きの値が範囲内にあるポリシーを持つ操作を呼び出すことによって、Azure portal または開発者ポータルでテストできます。 次の例では、前の 2 つのサンプル set-header ポリシーと名前付きの値で操作が呼び出されています。 応答に、ポリシーと名前付きの値を使用して構成された 2 つのカスタム ヘッダーが含まれていることに注意してください。

API 応答をテストする

送信 API トレースを見て、前の 2 つのサンプル ポリシーと名前付きの値が含まれる呼び出しを探すと、名前付きの値が挿入された 2 つの set-header ポリシーと、ポリシー式が含まれる名前付きの値のポリシー式評価を確認できます。

API Inspector トレース

注意事項

ポリシーで Azure Key Vault 内のシークレットが参照されている場合、キー・コンテナーの値は、そのAPI 要求トレースが有効になっているサブスクリプションにアクセスできるユーザーに表示されます。

名前付きの値にはポリシー式を含めることができますが、他の名前付きの値を含めることはできません。 名前付きの値参照を含むテキストが Text: {{MyProperty}} などの値に使用されている場合、その参照は解決されず、置き換えられません。

名前付きの値を削除する

名前付きの値を削除するには、名前を選択して、コンテキスト メニュー ( ... ) から [削除] を選択します。

重要

名前付きの値がいずれかの API Management ポリシーで参照されている場合は、それが使用されているすべてのポリシーから削除してからでないと削除できません。

次のステップ