Azure API Management のポリシー

  • [アーティクル]

Azure API Management API パブリッシャーは、ポリシーを使用した構成で API の動作を変更できます。 API の要求または応答に対して順番に実行される一連のステートメントが集まってポリシーが形成されます。 これらのステートメントには、次のものがあります。

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

他にも多数のポリシーが標準で提供されています。 完全な一覧については、「API Management ポリシー リファレンス」をご覧ください。

ポリシーは、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 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>

次のステップ

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