Azure API Management のポリシー

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

Azure API Management では、API パブリッシャーはポリシーを使用して構成を通じて API の動作 を変更できます。 この記事では、ポリシーの使用方法について説明します。

API の要求または応答に対して順番に実行される一連のステートメントが集まってポリシーが形成されます。 API Management には、認証、レート制限、キャッシュ、要求または応答の変換などの一般的な API シナリオに対応するように構成できる、75 を超えるポリシーが用意されています。 完全な一覧については、「API Management ポリシー リファレンス」をご覧ください。

注

API Management ポリシーは、Azure Policy 定義とは異なります。 API Management ポリシーは、API 要求と応答の変換、検証、セキュリティ保護、およびルーティングを行うためにゲートウェイ内で実行されるランタイム ルールです。 これに対し、Azure Policyは、組織または規制の要件を持つ API Management インスタンスなどのAzure リソースのコンプライアンスを評価して適用するガバナンス サービスです。

一般的なポリシーには次のようなものがあります:

  • XML から JSON への形式変換。
  • 開発者からの着信呼び出しの数を制限する通話レート制限。
  • 特定の IP アドレスから送信された要求のフィルター処理。

ポリシーは、API コンシューマーとマネージド API の間に配置されたゲートウェイ内で適用されます。 ゲートウェイは要求を受信し、変更されていない状態で基になる API に転送しますが、ポリシーは受信要求と送信応答の両方に変更を適用できます。

ポリシー構成について

ポリシー定義は、要求と応答に適用する一連のステートメントを記述する単純な XML ドキュメントです。 ポリシー定義の構成に役立つポータルには、次のオプションがあります。

  • XML をコーディングせずに一般的なポリシーを簡単に構成するためのガイド付きフォームベース エディター
  • XML スニペットを挿入したり、XML を直接編集したりできるコード エディター

ポリシーを構成する方法の詳細については、「ポリシーの設定または編集」をご覧ください。

ポリシー XML 構成は、inbound、backend、outbound、および on-error の各セクションに分かれています。 この一連の指定されたポリシー ステートメントは、要求と応答の順序で実行されます。 次のように表示されます。

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there's an error condition go here -->
  </on-error>
</policies>

ポリシー XML の例については、「API Management ポリシー スニペットのリポジトリ」を参照してください。

エラー処理

要求の処理中にエラーが発生した場合:

  • inbound、backend、outbound セクションの残りのステップはすべてスキップされます。
  • 実行は on-error セクションのステートメントにジャンプします。

ポリシー ステートメントを on-error セクションに配置することで、以下が可能になります。

  • context.LastError プロパティを使用してエラーを確認します。
  • set-body ポリシーを使用して、エラー応答を検査してカスタマイズします。
  • エラーが発生した場合の処理を構成します。

詳細については、「API Management のポリシーにおけるエラー処理」を参照してください。

ポリシー式

ポリシー式は、ポリシーで特に指定されていない限り、任意の API Management ポリシーで属性値またはテキスト値として使用できます。 ポリシー式は次のいずれかです。

  • で囲まれた単一の C# ステートメント @(expression)
  • 値を返す、 @{expression}で囲まれた複数ステートメントの C# コード ブロック

それぞれの式は、暗黙的に指定された context 変数と、許可されている .NET Framework の型のサブセットにアクセスできます。

ポリシー式は、特殊なコードの記述やバックエンド サービスの変更を必要とせずに、トラフィックを制御し、API の動作を変更するための高度な手段を提供します。 ポリシーの中には、制御フローや変数の設定のように、ポリシー式に基づいたものがあります。

スコープ

API Management を使用すると、以下のスコープでポリシーを定義できます。ここに示す範囲は、最も広いものから最も狭いものまでです。

  • グローバル (すべての API)
  • ワークスペース (選択したワークスペースに関連付けられているすべての API)
  • 製品 (選択した製品に関連付けられているすべての API)
  • API (API 内のすべての操作)
  • 操作 (API での 1 つの操作)

ポリシーを構成するとき、ポリシーを適用するスコープを最初に選択する必要があります。

5 つのポリシー スコープを示す図。

注意事項

  • さまざまな API コンシューマーに対してきめ細かな制御を行うには、複数のスコープでポリシー定義を構成できます。

  • 各スコープとポリシー セクションですべてのポリシーがサポートされているわけではありません。

  • ポリシー定義を複数のスコープで構成する場合は、 base 要素の配置によって、ポリシーの継承とポリシー評価の順序を各ポリシー セクションで制御します。

    Important

    ベスト プラクティスとして、各ポリシー セクションの先頭に base 要素を含めて、親スコープからポリシーを継承します。 これにより、上位レベルで定義されたポリシーが誤ってオーバーライドされたり無視されたりすることがなくなります。 組み込みの Azure Policy 定義 (API Management policies should inherit parent scope policies using <base/>) を使用して、このベスト プラクティスを監査または適用できます。

  • また、API 要求に適用されるポリシーは、要求コンテキストの影響を受けます。要求で使用されるサブスクリプション キーの有無、サブスクリプション キーの API または製品スコープ、API または製品にサブスクリプションが必要かどうかなどです。

    注

    API スコープ サブスクリプション、すべての API のサブスクリプション、または組み込みのすべてのアクセス許可を持つサブスクリプションを使っている場合、製品スコープで構成されたポリシーは、そのサブスクリプションからの要求には適用されません。

詳細については、次を参照してください:

GraphQL リゾルバー ポリシー

API Management では、 GraphQL リゾルバー は、 GraphQL スキーマ内の特定の操作の種類とフィールドにスコープが設定されたポリシーで構成されます。

  • 現在、API Management では、HTTP API、Azure Cosmos DB、または Azure SQL データ ソースのいずれかを指定する GraphQL リゾルバーがサポートされています。 たとえば、HTTP データ ソースへの要求 (および必要に応じて応答) を指定する要素を含む単一の http-data-source ポリシーを構成できます。
  • API、製品、すべての API など、他のスコープのポリシー定義にリゾルバー ポリシーを含めることはできません。 ポリシーは、他のスコープで構成されたポリシーも継承しません。
  • ポリシー実行パイプラインで構成されているすべての inbound と backend のポリシーの後で、ゲートウェイによってリゾルバースコープのポリシーが評価されます。

詳細については、「GraphQL リゾルバーの構成」を参照してください。

Copilot のサポートを受ける

Copilot から AI の支援を受けて、API Management ポリシー定義を作成および編集できます。 Copilot を使用すると、XML 構文を知らなくても、特定の要件に一致するポリシーを作成および更新できます。 既存のポリシーの説明を取得することもできます。 また、Copilot は、他の API 管理ソリューションで構成したポリシーを翻訳するのに役立ちます。

  • Azure Copilot は、Azure portal で自然言語プロンプトを使用してポリシー作成の支援を提供します。 API Management ポリシー エディターでポリシーを作成し、ポリシー セクションの説明を Copilot に依頼できます。
  • Visual Studio Code の GitHub Copilot for Azure では、Visual Studio Code でポリシー作成の支援が提供され、 Visual Studio Code 用の Azure API Management 拡張機能 を使用してポリシー構成を高速化できます。 自然言語で Copilot Chat または Copilot Edits にプロンプトを表示して、ポリシー定義を作成して調整することができます。

プロンプトの例:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot では AI を利用しているため、想定外のことや間違いが起こる可能性があります。 詳細については、「Copilot の一般的な使用に関する FAQ」を参照してください。

例

さまざまなスコープで指定されたポリシーを適用する

グローバル レベルのポリシーと、特定の API に対して設定されたポリシーがある場合、その特定の API が使用されるたびに両方のポリシーを適用できます。 API Management では、base 要素を介してポリシー ステートメントの組み合わせの順序を指定できます。

API スコープでのポリシー定義の例:

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

前のポリシー定義の例では、次のようになります。

  • cross-domain ステートメントが最初に実行されます。
  • find-and-replace ポリシーはより広範な範囲のポリシーの後に実行されます。

注

API スコープで base 要素を削除すると、API スコープで構成されたポリシーだけが適用されます。 製品およびより広範なスコープで構成されたポリシーは適用されません。

ポリシー式を使用して要求を変更する

次の例では、 ポリシー式 と set-header ポリシーを使用して、受信要求にユーザー データを追加します。 追加されたヘッダーには、要求のサブスクリプション キーに関連付けられているユーザー ID と、要求を処理するゲートウェイがホストされているリージョンが含まれます。

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

関連コンテンツ

ポリシーに対する処理の詳細については、次のトピックを参照してください:

  • Last updated on