API Management ポリシーの詳細
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>