Azure API Management のポリシーPolicies in Azure API Management

Azure API Management (APIM) のポリシーは、発行者がその構成を通じて API の動作を変更できる、システムの強力な機能の 1 つです。In Azure API Management (APIM), policies are a powerful capability of the system that allow the publisher to change the behavior of the API through configuration. ポリシーは、API の要求または応答に対して順に実行される一連のステートメントのコレクションです。Policies are a collection of Statements that are executed sequentially on the request or response of an API. 代表的なステートメントとしては、XML 形式から JSON 形式への変換や、(開発者からの呼び出しの回数を制限する) 呼び出しレート制限が挙げられます。Popular Statements include format conversion from XML to JSON and call rate limiting to restrict the amount of incoming calls from a developer. 他にも多数のポリシーが標準で提供されています。Many more policies are available out of the box.

ポリシーは、API コンシューマーとマネージド API の間に配置されたゲートウェイ内で適用されます。Policies are applied inside the gateway which sits between the API consumer and the managed API. ゲートウェイは、すべての要求を受け取り、通常はそれらの要求をそのまま基底の API に転送します。The gateway receives all requests and usually forwards them unaltered to the underlying API. ただし、ポリシーを使用すると、受信要求と送信応答の両方に変更を適用できます。However a policy can apply changes to both the inbound request and outbound response.

ポリシーの式は、ポリシーで特に指定されていない限り、任意の API Management ポリシーで属性値またはテキスト値として使用できます。Policy expressions can be used as attribute values or text values in any of the API Management policies, unless the policy specifies otherwise. 制御フロー ポリシーや変数の設定ポリシーなど、一部のポリシーはポリシーの式に基づいています。Some policies such as the Control flow and Set variable policies are based on policy expressions. 詳細については、「詳細なポリシー」と「ポリシーの式」をご覧ください。For more information, see Advanced policies and Policy expressions.

ポリシー構成について Understanding policy configuration

ポリシー定義は、一連の受信ステートメントと送信ステートメントが記述された単純な XML ドキュメントです。The policy definition is a simple XML document that describes a sequence of inbound and outbound statements. XML は、定義ウィンドウで直接編集できます。The XML can be edited directly in the definition window. ウィンドウの右側にはステートメントの一覧が表示され、現在のスコープに適用できるステートメントが有効になり強調表示されます。A list of statements is provided to the right and statements applicable to the current scope are enabled and highlighted.

有効なステートメントをクリックすると、定義ビュー内のカーソル位置に適切な XML が追加されます。Clicking an enabled statement will add the appropriate XML at the location of the cursor in the definition view.

注意

追加するポリシーが有効になっていない場合、そのポリシー用の正しいスコープが選択されていることを確認してください。If the policy that you want to add is not enabled, ensure that you are in the correct scope for that policy. 各ポリシー ステートメントは、特定のスコープおよびポリシー セクション内で使用するように設計されています。Each policy statement is designed for use in certain scopes and policy sections. ポリシーのポリシー セクションとスコープを確認するには、ポリシー リファレンスに関するページでそのポリシーの使用例を参照してください。To review the policy sections and scopes for a policy, check the Usage section for that policy in the Policy Reference.

構成は inboundbackendoutbound、および on-error に分かれます。The configuration is divided into inbound, backend, outbound, and on-error. 要求および応答に対して、指定された一連のポリシー ステートメントが順に実行されます。The series of specified policy statements is executes in order for a request and a response.

<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> 

要求の処理中にエラーが発生した場合、inboundbackend、または outbound セクションの残りの手順はスキップされ、実行は on-error セクションのステートメントにジャンプします。If there is an error during the processing of a request, any remaining steps in the inbound, backend, or outbound sections are skipped and execution jumps to the statements in the on-error section. on-error セクションにポリシー ステートメントを配置することで、context.LastError プロパティを使用してエラーを確認し、set-body ポリシーを使用してエラーの検査とカスタマイズを行い、エラーが発生した場合の動作を構成できます。By placing policy statements in the on-error section you can review the error by using the context.LastError property, inspect and customize the error response using the set-body policy, and configure what happens if an error occurs. 組み込み手順用と、ポリシー ステートメントの処理中に発生する可能性があるエラー用のエラー コードがあります。There are error codes for built-in steps and for errors that may occur during the processing of policy statements. 詳細については、 API Management のポリシーにおけるエラー処理に関するページを参照してください。For more information, see Error handling in API Management policies.

ポリシーの構成方法 How to configure policies

ポリシーの構成方法については、ポリシーの設定と編集に関する記事をご覧ください。For information on how to configure policies, see Set or edit policies.

ポリシー リファレンスPolicy Reference

ポリシー ステートメントとその設定の一覧については、ポリシー リファレンスに関する記事をご覧ください。See the Policy reference for a full list of policy statements and their settings.

ポリシーのサンプルPolicy samples

コード サンプルの詳細については、ポリシーのサンプルに関する記事をご覧ください。See Policy samples for more code examples.

Examples

さまざまなスコープで指定されたポリシーを適用するApply policies specified at different scopes

グローバル レベルのポリシーと API 向けに構成されたポリシーがある場合、API が使用されるたびに両方のポリシーが適用されます。If you have a policy at the global level and a policy configured for an API, then whenever that particular API is used both policies will be applied. API Management では、基本要素を介してポリシー ステートメントの組み合わせの順序を指定できます。API Management allows for deterministic ordering of combined policy statements via the base element.

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

上のポリシー定義の例では、cross-domain ステートメントが上位のポリシーよりも前に実行され、その後に find-and-replace ポリシーが続いています。In the example policy definition above, the cross-domain statement would execute before any higher policies which would in turn, be followed by the find-and-replace policy.

受信要求を制限するRestrict incoming requests

新しいステートメントを追加して受信要求を指定された IP アドレスに制限するには、inbound XML 要素内にカーソルを置き、 [Restrict caller IPs](呼び出し元 IP の制限) ステートメントをクリックします。To add a new statement to restrict incoming requests to specified IP addresses, place the cursor just inside the content of the inbound XML element and click the Restrict caller IPs statement.

制限ポリシー

これで、ステートメントを構成する方法を示す XML スニペットが inbound 要素に追加されます。This will add an XML snippet to the inbound element that provides guidance on how to configure the statement.

<ip-filter action="allow | forbid">
    <address>address</address>
    <address-range from="address" to="address"/>
</ip-filter>

受信要求を制限して、IP アドレス 1.2.3.4 からの要求のみを受け付けるには、次のように XML を変更します。To limit inbound requests and accept only those from an IP address of 1.2.3.4 modify the XML as follows:

<ip-filter action="allow">
    <address>1.2.3.4</address>
</ip-filter>

次の手順Next steps

ポリシーを使用する方法の詳細については、次のトピックを参照してください。For more information working with policies, see: