Azure API Management のポリシー

  • [アーティクル]

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

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

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

  • 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 is 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 ポリシーで属性値またはテキスト値として使用できます。 ポリシー式は次のいずれかです。

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

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

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

スコープ

API Management では、最も広範なものから最も狭小なものまで、次のスコープでポリシーを定義できます。

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

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

ポリシー スコープ

注意事項

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

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

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

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

    Note

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

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

GraphQL リゾルバー ポリシー

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

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

詳細については、GraphQL リゾルバーの構成に関するページを参照してください。

Microsoft Copilot in Azure (プレビュー) を使ったポリシーの作成についてサポートを受ける

Microsoft Copilot in Azure (プレビュー) には、Azure API Management のポリシー作成機能があります。 API Management のポリシー エディターのコンテキストで Copilot in Azure を使うと、構文を知らなくても特定の要件に合致するポリシーを作成したり、構成済みのポリシーについての説明を受けたりすることができます。

Copilot in Azure にポリシー定義を生成するようにプロンプトを指定し、その結果をポリシー エディターにコピーして、必要な調整を行うことができます。 質問してさまざまなオプションについて分析情報を得る、提供されたポリシーを変更する、または既存のポリシーを明確することができます。 詳細情報

例

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

グローバル レベルのポリシーと、特定の 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 ポリシーは、より広いスコープのポリシーの後に実行されます。

Note

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>

関連するコンテンツ

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