API Management ポリシーの詳細

3 分

Azure API Management ではポリシーを利用することで、パブリッシャーは構成を通じて API の動作を変更できます。ポリシーは、API の要求または応答に対して順に実行される一連のステートメントのコレクションです。

ポリシーは、API コンシューマーとマネージド API の間に配置されたゲートウェイ内で適用されます。ゲートウェイは、すべての要求を受け取り、通常はそれらの要求をそのまま基底の API に転送します。ただし、ポリシーを使用すると、受信要求と送信応答の両方に変更を適用できます。ポリシーの式は、ポリシーで特に指定されていない限り、任意の API Management ポリシーで属性値またはテキスト値として使用できます。

ポリシー構成について

ポリシー定義は、一連の受信ステートメントと送信ステートメントが記述された単純な 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>

要求の処理中にエラーが発生した場合、inbound、backend、または outbound セクションの残りの手順がスキップされ、実行は on-error セクションのステートメントにジャンプします。 on-error セクションにポリシーステートメントを配置することで、context.LastError プロパティを使用してエラーを確認し、set-body ポリシーを使用してエラーの検査とカスタマイズを行い、エラーが発生した場合の動作を構成できます。

ポリシー式

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

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

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

ポリシー式は、特殊なコードの記述やバックエンドサービスの変更を必要とせずに、トラフィックを制御し、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>

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

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

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

前のポリシー定義の例では、cross-domain ステートメントが最初に実行されます。 find-and-replace ポリシーは、より広いスコープのポリシーの後に実行されます。

応答の内容をフィルターする

次の例で定義されているポリシーは、要求に関連付けられている製品に基づき、応答ペイロードからデータ要素をフィルター処理する方法を示しています。

このスニペットでは、応答コンテンツが JSON として書式設定され、minutely、hourly、daily、flags という名前のルートレベルのプロパティを含んでいることを想定しています。

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

API Management ポリシーの詳細

ポリシー構成について

ポリシー式

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

応答の内容をフィルターする

フィードバック