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

適用対象: すべての API Management レベル

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

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

値の型

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

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

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

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

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

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

前提条件

• API Management サービス インスタンスをまだ作成していない場合は、「 クイック スタート: Azure portal を使用して新しい Azure API Management インスタンスを作成する」を参照してください。

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

• まだキー コンテナーがない場合は作成します。 キー コンテナーを作成する手順については、「クイックスタート: Azure portal を使用してキー コンテナーを作成する」を参照してください。

  キー コンテナーにシークレットを作成またはインポートする方法については、「クイック スタート: Azure portal を使用して Azure Key Vault との間でシークレットの設定と取得を行う」を参照してください。

• API Management インスタンスで、システムによって割り当てられた、またはユーザーが割り当てたマネージド ID を有効にします。

キー コンテナーへのアクセスを構成する

1. ポータルでキー コンテナーに移動します。
2. 左側のメニューで、[設定]>[Access の構成] を選択します。 構成されている アクセス許可モデル に注意してください。
3. アクセス許可モデルに応じて、API Management マネージド ID のキー コンテナー アクセス ポリシーまたは Azure RBAC アクセスを構成します。

キー コンテナーのアクセス ポリシーを追加するには:

1. 左側のメニューで、[アクセス ポリシー] を選択します。
2. [アクセス ポリシー] ページで、[+ 作成] を選択します。
3. [ アクセス許可 ] タブの [ シークレットのアクセス許可] で、[ 取得 と 一覧表示] を選択し、[ 次へ] を選択します。
4. [ プリンシパル ] タブで、マネージド ID のリソース名を検索し、[ 次へ] を選択します。 システムによって割り当てられた ID を使用している場合、プリンシパルは API Management インスタンスの名前です。
5. もう一度 [次へ] を選択します [確認および作成] タブで、[作成] を選択します。

Azure RBAC アクセスを構成するには:

1. 左側のメニューで [アクセス制御 (IAM)] を選択します。
2. [アクセス制御 (IAM)] ページで、[ロールの割り当てを追加] を選択します。
3. [ ロール ] タブで、[ Key Vault シークレット ユーザー] を選択し、[ 次へ] を選択します。
4. [メンバー] タブで、[マネージド ID]>[+ Select members] (+ メンバーの選択) を選択します。
5. [Select managed identity] (マネージド ID の選択) ページで、API Management インスタンスに関連付けられているシステム割り当てマネージド ID またはユーザー割り当てマネージド ID を選択し、[選択] を選択します。
6. [確認と割り当て] を選択します。

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

Key Vault のファイアウォールがキー コンテナーで有効になっている場合は、次の要件を満たす必要があります。

• キー コンテナーにアクセスするには、API Management インスタンスのシステム割り当てマネージド ID を使用する必要があります。

• Key Vault ファイアウォールで、[Allow Trusted Microsoft Services to bypass this firewall]\(信頼された Microsoft サービスがこのファイアウォールをバイパスすることを許可する\) オプションを有効にします。

• Azure API Management に追加する証明書またはシークレットを選択するときに、ローカル クライアントの IP アドレスがキー コンテナーへの一時的なアクセスを許可されるようにする必要があります。 詳細については、「Azure Key Vault のネットワーク設定を構成する」を参照してください。

  構成が完了したら、Key Vault ファイアウォールでクライアント アドレスをブロックできます。

仮想ネットワークの要件

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

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

詳細については、 仮想ネットワークで API Management を設定するときのネットワーク構成に関するページを参照してください。

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

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

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

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

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

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

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

5. [種類] ドロップダウン リストで、[キー ボールト] を選択します。

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

   重要

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

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

   注

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

8. [ 保存] を選択し、[ 作成] を選択します。

   

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

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

名前付きの値を使用する

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

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

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

この例では、ContosoHeader は set-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 トレースを見て、前の 2 つのサンプル ポリシーと名前付きの値が含まれる呼び出しを探すと、名前付きの値が挿入された 2 つの set-header ポリシーと、ポリシー式が含まれる名前付きの値のポリシー式評価を確認できます。

名前付き値で文字列補間を使用することもできます。

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

CustomHeader の値は The URL encoded value is This+is+a+header+value. になります。

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

名前付きの値を削除する

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

関連コンテンツ

ポリシーの操作の詳細については、以下を参照してください。

• API Management のポリシー
• Policy reference (ポリシー リファレンス)
• ポリシー式