Azure API Management のポリシー

Azure API Management (APIM) のポリシーは、発行者がその構成を通じて API の動作を変更できる、システムの強力な機能の 1 つです。 ポリシーは、API の要求または応答に対して順に実行される一連のステートメントのコレクションです。 代表的なステートメントとしては、XML 形式から JSON 形式への変換や、(開発者からの呼び出しの回数を制限する) 呼び出しレート制限が挙げられます。 他にも多数のポリシーが標準で提供されています。

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

ポリシーの式は、ポリシーで特に指定されていない限り、任意の API Management ポリシーで属性値またはテキスト値として使用できます。 制御フロー ポリシーや変数の設定ポリシーなど、一部のポリシーはポリシーの式に基づいています。 詳細については、「詳細なポリシー」と「ポリシーの式」をご覧ください。

ポリシー構成について

ポリシー定義は、一連の受信ステートメントと送信ステートメントが記述された単純な XML ドキュメントです。 XML は、定義ウィンドウで直接編集できます。 ウィンドウの右側にはステートメントの一覧が表示され、現在のスコープに適用できるステートメントが有効になり強調表示されます。

有効なステートメントをクリックすると、定義ビュー内のカーソル位置に適切な XML が追加されます。

注意

追加するポリシーが有効になっていない場合、そのポリシー用の正しいスコープが選択されていることを確認してください。 各ポリシー ステートメントは、特定のスコープおよびポリシー セクション内で使用するように設計されています。 ポリシーのポリシー セクションとスコープを確認するには、ポリシー リファレンスに関するページでそのポリシーの 使用例 を参照してください。

構成は inboundbackendoutbound、および 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> 

要求の処理中にエラーが発生した場合、inboundbackend、または outbound セクションの残りの手順はスキップされ、実行は on-error セクションのステートメントにジャンプします。 on-error セクションにポリシー ステートメントを配置することで、context.LastError プロパティを使用してエラーを確認し、set-body ポリシーを使用してエラーの検査とカスタマイズを行い、エラーが発生した場合の動作を構成できます。 組み込み手順用と、ポリシー ステートメントの処理中に発生する可能性があるエラー用のエラー コードがあります。 詳細については、 API Management のポリシーにおけるエラー処理に関するページを参照してください。

ポリシーの構成方法

ポリシーの構成方法については、ポリシーの設定と編集に関する記事をご覧ください。

ポリシー リファレンス

ポリシー ステートメントとその設定の一覧については、ポリシー リファレンスに関する記事をご覧ください。

ポリシーのサンプル

コード サンプルの詳細については、ポリシーのサンプルに関する記事をご覧ください。

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

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

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

上のポリシー定義の例では、cross-domain ステートメントが上位のポリシーよりも前に実行され、その後に find-and-replace ポリシーが続いています。

受信要求を制限する

新しいステートメントを追加して受信要求を指定された IP アドレスに制限するには、inbound XML 要素内にカーソルを置き、[Restrict caller IPs](呼び出し元 IP の制限) ステートメントをクリックします。

制限ポリシー

これで、ステートメントを構成する方法を示す XML スニペットが inbound 要素に追加されます。

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

受信要求を制限して、IP アドレス 1.2.3.4 からの要求のみを受け付けるには、次のように XML を変更します。

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

次のステップ

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