適切な API Management ポリシーを選択する
API Management ポリシーを使用することで、そのコードを書き直すことなく、デプロイされた API の動作を制御できます。
ボード ゲーム会社には、パートナー組織で価格の見積もりを取得し、スタッフ メンバーが在庫レベルを確認し、顧客が注文できる一連の API があります。 パフォーマンスに関する特定の問題に対処し、ポリシーを使用して他に何を実現できるかを調べたいと思っています。
まず、ポリシーを使用して何ができるかを見てみましょう。
ポリシーとは
Azure API Management では、管理者はポリシーを使用し、構成を通じて API の動作を変更することができます。 API の主な機能と動作は、コードを記述する開発者によって設計されています。 しかし、管理者はポリシーを使用して、制限を設定したり、応答形式を変換したり、セキュリティ要件を適用したりすることができます。 このモジュールでは、ポリシーを使用してキャッシュを設定し、制御することに集中します。
ポリシーは、順番に実行される個々のステートメントで構成されます。 ポリシー ドキュメントは XML 構造体であり、これらには、API の動作を制御するために使用できる要素が含まれます。
ポリシーが実行されるタイミング
Azure API Management では、ポリシーは次の 4 つの異なるタイミングで実行されます。
- インバウンド: これらのポリシーは、クライアントから要求を受信したときに実行されます。
- バックエンド: これらのポリシーは、要求がマネージド API に転送される前に実行されます。
- アウトバウンド: これらのポリシーは、応答がクライアントに送信される前に実行されます。
- エラー時: これらのポリシーは、例外が発生したときに実行されます。
ポリシー XML では、これらの実行時間ごとに別のタグがあります。
<policies>
<inbound>
<base />
<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
</check-header>
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
<json-to-xml apply="always" consider-accept-header="false" parse-date="false" />
</outbound>
<on-error>
<base />
</on-error>
</policies>
この例では、受信要求の Authorization という名前のヘッダーがポリシーで確認されていることがわかります。 このようなヘッダーが存在しない場合、ポリシーでエラー メッセージが表示されます。
また、このポリシーでは、JSON 形式の送信応答が XML に変換されます。
ポリシー スコープ
ポリシーのスコープでは、適用される範囲が決定されます。 次に選択できるポリシー スコープを示します。
- グローバル
- Product
- API
- 操作
グローバル
グローバル スコープで適用されるポリシーは、API Management のインスタンス内のすべての API に影響します。
グローバル スコープを使用するには、[API Management サービス] ペインの左側のメニュー ペインにある [API Management] の下で、[API] を選択し、中央のメニュー ペインで [すべての API] を選択します。 [受信処理] または [送信処理] セクションで [ポリシーの追加] を選択すると、そのスコープで追加できるポリシーが表示されます。
使用可能な選択肢から、正しい構文を使ってポリシーを追加するためのウィザードを開始する選択を行います。
[受信処理]、[送信処理]、または [バックエンド] セクションでタグ シンボル </> を選択することで、XML エディターを開くことができます。 表示されるポリシー エディターには、既定の XML コンテンツが含まれています。 右側の [スニペットの表示] を選択して、ポリシーを追加するショートカットを見つけます。
Product
API Management では、1 つまたは複数の API を単一の製品にアセンブルしてから、単一のエンティティとしてその製品へのアクセスを管理することができます。 製品スコープで適用されるポリシーは、その製品のすべての API に影響します。 その他の製品の API は影響を受けません。 Azure portal で製品を管理する場合は、ガイド付きウィザードまたは XML ポリシー エディターを使用してポリシーを追加する [ポリシー] ペインを選択してください。
API
API スコープで適用されるポリシーは、単一の API のみに影響します。 API スコープでポリシーを設定するには、API Management のホーム ページで [API] を選んでから、管理する API を選びます。 最後に、[デザイン] タブで、[すべての操作] を選択してください。 その API のすべての操作に適用する受信、送信、またはバックエンドのポリシーを設定できます。
操作
操作スコープに適用されるポリシーは、API 内の 1 つの操作のみに影響します。 以下の例では、管理者が Demo Conference API 内の GetSpeaker 操作を選択しており、その操作にのみ適用される受信、送信、またはバックエンド ポリシーを設定することができます。
ポリシーが適用される順序
<base /> タグを使用して、上位スコープからのポリシーが適用されるタイミングを決定することができます。 たとえば、API スコープで適用される、このポリシーについて考えてみます。
<policies>
<inbound>
<base />
<find-and-replace from="game" to="board game" />
</inbound>
</policies>
<base> タグは <find-and-replace> タグの上に表示されるため、Azure API Management により、まず、グローバルおよび製品スコープからのポリシーが適用され、次に検索と置換ポリシーが実行されます。
よく使用されるポリシー
API Management でポリシーを使って実行できることをいくつか確認しましょう。 最もよく使用されるポリシーの一部を紹介します。完全なリストと例については、API Management のドキュメントを参照してください。
アクセスを制限するためのポリシー
API またはその操作へのアクセスを禁止または制限するために使用できるポリシーがいくつかあります。 たとえば次のような点です。
HTTP ヘッダーのプロパティを確認する場合は、HTTP ヘッダーを確認するポリシーを使用します。 プロパティが見つからない場合、Azure API Management によって要求が削除されます。
呼び出しレートをサブスクリプション別に制限するポリシーでは、単一の API サブスクリプションから実行可能な呼び出しの数が制限されます。 このポリシーでは、確実に、1 つのサブスクリプションのユーザーがすべての帯域幅を使用しないようにすることができます。
単一のアクセス キーで到着する呼び出しの数を制限する場合は、呼び出しレートをキー別に制限するポリシーを使用します。
特定の IP アドレスまたは IP アドレスの範囲からの呼び出しを許可または拒否するには、呼び出し元 IP を制限するポリシーを使用します。 アクセスを制限するこの方法は、ファイアウォールに適用できる IP アドレスの制限のように動作します。
認証のためのポリシー
いくつかのポリシーで認証を制御することができます。 たとえば次のような点です。
基本認証ポリシーを使用して、プレーン テキストでの認証を有効にすることができます。 この形式の認証は広くサポートされていますが、SSL 暗号化で保護する必要があることに注意してください。そうしなければ、ネットワークを通過するときに悪意のある攻撃によって資格情報が傍受されるおそれがあります。
クライアント証明書を指定してクライアントを認証できるようにするには、クライアント証明書による認証ポリシーを使用します。
クロスドメイン ポリシー
クロス メイン要求はセキュリティの脅威と見なされ、ブラウザーおよび API によって拒否されます。 しかし、特定の操作では望ましい場合があり、API Management ポリシーを使って安全に許可することができます。
Adobe Flash と Silverlight からの呼び出しを許可するには、クロスドメイン呼び出しを許可ポリシーを使用します。 API またはクライアント アプリがクロスオリジン リソース共有 (CORS) に依存している場合は、CORS ポリシーを使用してそれらを許可します。
ブラウザー上で実行される、一部の AJAX コードでは、JSON with Padding を使用して安全にクロスドメイン呼び出しを行います。 クライアントでこの手法を使用することを許可するには、JSONP ポリシーを使います。
変換ポリシー
多くの場合、マネージド API からの応答の形式またはコンテンツを変更するのに役立ちます。 これはいくつかのポリシーを使用して行うことができます。 たとえば次のような点です。
JSON と XML 間で変換するには、JSON から XML への変換および XML から JSON への変換ポリシーを使用します。 このポリシーは多くの場合、製品の複数の API の一貫性を維持するのに役立ちます。 また、アプリで特定の形式の応答が予期される場合は、API を再コード化する必要がなくなります。
XML での応答を保持するが、そのスキーマを変更する必要がある場合があります。 そのような場合は、XML の変換ポリシーを使用して、XSLT テンプレートを適用します。
文字列の置換を実行するには、本文内の文字列の検索および置換を使用します。 たとえば、ブランド名が変更された場合、基になるデータにまだ古い名前への参照が含まれている場合でも、このポリシーを使用して、確実にその変更がすべての応答に反映されるようにすることができます。
コンテンツ内の URL のマスク ポリシーでは、応答本文内のリンクを書き直し、それらが別の場所を指すようにすることができます。 このポリシーは、Web サイトまたは Web API が移動された場合に役立ちます。
着信および発信要求のメッセージ テキストを設定するには、本文の設定ポリシーを使用します。
着信した HTTP 要求または発信する応答を変更する場合は、複数の異なるポリシーを使用できます。 既存の応答または要求ヘッダーに項目を追加するには、HTTP ヘッダーの設定ポリシーを使用します。 URL の疑問符の後に表示される、クエリ文字列を変更する必要がある場合は、クエリ文字列パラメーターの設定ポリシーを使用します。 ユーザーが要求したパブリック URL を別の内部宛先にマップする必要がある場合、URL の書き換えポリシーで、受信と送信の両方の変換を行うことができます。
高度なポリシー
非標準の動作が必要なシナリオでは、これらのポリシーが役立つ場合があります。
たとえば、応答が特定のテストに合格したときにのみ、ポリシーを適用する場合は、制御フロー ポリシーを使用します。
要求をバックエンド サーバーに転送するには、要求を転送するポリシーを使用します。
アクションが失敗したときの動作を制御するには、再試行ポリシーを使用します。 Retry で囲まれたポリシー ステートメントは、条件が満たされるまで繰り返し実行されます。 実行は、再試行回数値に達するまで、指定された間隔で繰り返されます。
1 方向の要求を送信するポリシーでは、応答を待機することなく、URL に要求を送信することができます。
以降の計算またはテストに使用する値を格納する場合は、変数の設定ポリシーを使って、名前付き変数で値を保持します。