Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Add policies to your API

学習内容

このチュートリアルを通じて、以下のことを学びます。

  • API プロキシを作成します。
  • リクエストとレスポンスに影響を与えるポリシーを追加します。
  • ポリシーの効果を確認します。
  • Trace ツールで、メッセージの詳細を表示します。

Apigee Edge provides a lot of built-in functionality for managing traffic between clients and your target services, such as security, traffic limiting, and message transformation. This functionality is handled through policies that you attach to different points in the message flow through your API proxies. With policies, you can augment your target services without having to modify them.

このチュートリアルでは、以下の 2 つのことを行う API プロキシを作成します。

  • 突然のトラフィックスパイクからの保護
  • XML から JSON へのレスポンスの変換

API プロキシの呼び出しを行って実際のポリシーの動作を確認した後、Trace ツールで、メッセージの詳細を表示します。

必要なもの

  • Apigee Edge アカウント。まだ持っていない場合は、「Apigee Edge アカウントの作成」の指示に従ってサインアップできます。
  • cURL。コマンドラインから API 呼び出しを行うために、マシン上にインストールされている必要があります。

API プロキシの作成

About the 'mocktarget'

The mocktarget service is hosted at Apigee and returns simple data. It requires no API key or access token. In fact, you can access it in a web browser. Try it out by clicking the following:

http://mocktarget.apigee.net

The target returns Hello, Guest!. Use the /help resource to get a help page of other API resources that are available.

  1. https://enterprise.apigee.com に移動し、ログインします。これは Edge 管理 UI です。
  2. 上部のメニューの「APIs」をクリックします。
  3. 追加用の「(+) API Proxy」ボタンをクリックします。
  4. 「Build a Proxy」ウィザードで、「Reverse proxy (most common)」を選択し、「Next」をクリックします。
  5. 以下に従ってプロキシを構成します。
    フィールド 操作内容
    Proxy Name 次のように入力します: helloworld_policies
    Project Base Path

    Change to: /hellopolicies

    The Project Base Path is part of the URL used to make requests to the API proxy.

    Note: For Apigee's recommendations on API versioning, see Versioning in the Web API Design: The Missing Link e-book.

    Existing API

    次のように入力します: http://mocktarget.apigee.net/xml

    これは、Apigee Edge が API プロキシに対するリクエストで呼び出すターゲット URL を定義します。/xml リソースにより、サンプルの XML レスポンスが返されます。

    説明 次のように入力します: hello world with policies
  6. 「Next」をクリックします。
  7. 「Security」ページで、セキュリティオプションとして「Pass through (none)」を選択し、「Next」をクリックします。
  8. 「Virtual Hosts」ページで、「Next」をクリックします。
  9. 「Build」ページで、test 環境が選択されていることを確認し、「Build and Deploy」をクリックします。
  10. 「Summary」ページで、新しい API プロキシが正常に作成され、test 環境に展開されたことを示す確認応答が表示されます。
  11. 「View the helloworld_policies proxy in the editor」をクリックして、 API プロキシの「Overview」ページを表示します。

初期 API プロキシのテスト

端末ウィンドウで、次のコマンドを実行します。URL では、自分の組織名に置き換えてください。

curl "http://{org-name}-test.apigee.net/hellopolicies"

レスポンスとして、次のような内容が表示されます。

<?xml version="1.0" encoding="UTF-8"?> <root><city>San Jose</city><firstName>John</firstName><lastName>Doe</lastName><state>CA</state></root>

また、Web ブラウザに URL を入力して、整然とした形式でレスポンスを表示することもできます。

この時点で、API プロキシを呼び出すと、http://mocktarget.apigee.net/xml によってターゲットサービスを直接呼び出した場合と同じ結果が得られます。ただし、次の手順でポリシーを追加すると、API プロキシのレスポンスが変わります。

Spike Arrest policy

この手順では、突然のトラフィックスパイクからターゲットサービスを保護するように Spike Arrest ポリシーを構成します。突然のトラフィックスパイクは、使用率、バグのあるクライアント、または悪意のある攻撃の増加が原因である可能性があります。リクエスト数がレート制限を超えると、API から、あるリクエストについて HTTP 500 エラーが返されます。

次の手順で、API プロキシに Spike Arrest ポリシーを追加します。

  1. 新しい API プロキシのエディタで、「Develop」タブをクリックします。
    (API プロキシエディタを使用していない場合は、管理 UI のメニューで「APIs」 > 「API Proxies」 > 「helloworld_policies」を選択します。)


    API プロキシエディタを使用すると、API プロキシの構造を表示して、そのフローを構成することができます。このエディタでは、プロキシのリクエストおよびレスポンスメッセージフローが視覚的に表示されるだけでなく、プロキシを定義する、基盤となる XML の編集画面も表示されます。

  2. 左側の「Navigator」ウィンドウで、「Proxy Endpoints」の下にある「PreFlow」 > 「default」をクリックします (他のチュートリアルで、フローの概念を扱います)。
  3. Request プレフローに対応する一番上の「+Step」ボタンをクリックします。この操作により、作成できるすべてのポリシーの分類リストが表示されます。
    「Request PreFlow」で「Step」をクリックします。
  4. 「Traffic Management」カテゴリで、「Spike Arrest」を選択します。「New Policy」ダイアログが表示されます。
    Spike Arrest ポリシーの作成
  5. デフォルト名をそのまま残し、「Add」をクリックします。新しいポリシーは、リクエストの PreFlow フローに添付されます。
  6. Navigator で、「Proxy Endpoints」 > 「default」の下にある「PreFlow」が引き続き選択されていることを確認して、API プロキシエディタで以下を確認します。 
    • 新しい Spike Arrest-1 ポリシーが API プロキシエディタの左側にある Navigator の下の「Policies」に追加されている。
    • Spike Arrest-1 アイコンがプロキシのメッセージフローの視覚的な表示である API プロキシエディタの中央上側のデザイナビューに追加されている。
    • ポリシーの XML が、API プロキシエディタの中央下側にあるコードビューに表示されます。
    Spike Arrest ポリシーを含むプレフローの表示
  7. Navigator の「Policies」で Spike Arrest-1 を選択し、API プロキシエディタで以下を確認してください。
    • ポリシーの詳細が、API プロキシエディタの中央上側の デザイナビューに表示されている。
    • ポリシーの XML が API プロキシエディタの中央下側のコードビューに表示されている。
    • ポリシーの XML 要素と属性の値が、API プロキシエディタの右側にある「Property Inspector」に表示されます。
  8. ポリシーの XML では、<Rate> 要素の値を 1pm に変更します (これは、クラウド内で 60 秒ごとに約 2 件のリクエストが許可されるということに変換されます)。

    Spike Arrest の動作は、複数のメッセージプロセッサにわたった平滑化アルゴリズムに関与します。このアルゴリズムは、確認できる実際の動作に影響します。詳細については、「Spike Arrest policy reference」トピックを参照してください。

    レートには、毎分 (pm) または毎秒 (ps) 単位の整数値で指定できます。これは、非常に低い制限であり、ポリシーの実証を目的とするこのチュートリアル専用で使用されます。通常は、はるかに高い制限が設定されます。 

    Property Inspector の 「Rate」 値も 1pm に変わっていることに注目してください。代わりに、Property Inspector の「Rate」値を変更することもできます。これにより、値が XML ビューに反映されます。

  9. 現在のリビジョンを変更内容と一緒に保存するには、「Save」をクリックします。
  10. cURL を使用して、{org-name} を自分の Apigee 組織名に置き換えて、API を再び呼び出します。

    curl "http://{org-name}-test.apigee.net/hellopolicies"

    リクエストが成功し、以前と行ったときと同じ XML レスポンスが表示されていることを確認します (Web ブラウザに URL だけを入力することもできます)。

  11. 1 分以内に curlコマンド (または、ブラウザウィンドウの更新) をさらに 2、3 回実行し、ポリシーのレート制限を超えたために次のメッセージが表示されることを確認します。

    {"fault":{"faultstring":"Spike arrest violation. Allowed rate : 1pm","detail":{"errorcode":"policies.ratelimit.SpikeArrestViolation"}}}

    1 分以内にこれ以上の呼び出しを行おうとすると、障害メッセージが表示され続けます。

  12. ポリシーを編集して <Rate> 制限を 15pmに設定し (これは、クラウド内で 4 秒ごとに約 2 件のリクエストが許可されるということに変換されます)、API プロキシを保存します。
  13. 繰り返し cURL コマンドを実行するか、ブラウザを更新します (cURLの方が高速です)。4 秒間隔で 1、2 回呼び出しを行った場合、呼び出しが成功することを確認します。4 秒以内に 2 回を超えて素早く呼び出しを行った場合、障害が発生します。ただし、(1 pm 設定によって) まる 1 分間ブロックされるのではなく、4 秒間の期間が過ぎた後は、呼び出しを行い続けることができます。

XML to JSON Policy

サンプルターゲットからのレスポンスには XML データが含まれています。これは、アプリで API を通じてバックエンドサービスにアクセスしたいが、JSON レスポンスのみを受け入れたい開発者にとっては問題となる可能性があります。この問題を解決するには、API に、レスポンスデータを XML から JSON に変換する XML to JSON ポリシーを追加します。このポリシーは Edge 上で実行されるため、ターゲットサービスを変更することなくデータ変換を実行できます。

このポリシーを使用すると、XML レスポンスのペイロードが解析されて JSON に変換され、Content-Type ヘッダーが application/json に変更されます。このポリシーは、ソースの Content-Type ヘッダーが application/xml である場合にのみ機能します。

次の手順で、XML to JSON を追加します。

  1. API プロキシエディタで、「Proxy Endpoints」 > 「default」の下にある「PostFlow」をクリックして、そのフローにポリシーを追加します。 
  2. Response ポストフローに対応する一番下の「+Step」ボタンをクリックします。この操作により、作成できるすべてのポリシーの分類リストが表示されます。
  3. 「Mediation」カテゴリで「XML to JSON」を選択します。
  4. 「New Policy」ダイアログで、「Display Name」「Name」についてはデフォルト値を保持します。
  5. 「Add」をクリックします。XML to JSON ポリシーがレスポンスのポストフローのフローに適用されます。
    XML to JSON ポリシーが画面のデザイナエリアの Response の下に表示されていない場合は、Navigator の「Proxy Endpoints」 > 「default」の下にある「PostFlow」を選択します。Spike Arrest ポリシーを表示するには、「Proxy Endpoints」 > 「default」の下にある「PreFlow」を選択します。
    XML to JSON ポリシーを含むプレフローの表示
  6. 「Save」をクリックします。 
  7. cURL を使用して (または、Web ブラウザで URL のみを使用して)、{org-name} を自分の Apigee 組織名に置き換えて、API を再び呼び出します。

    curl "http://{org-name}-test.apigee.net/hellopolicies"

    レスポンスが JSON になったことに注意してください。

    {"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}
    

よくできました。API プロキシを作成し、その API プロキシに、トラフィックスパイクから保護し、XML レスポンスを JSON に変換するポリシーを追加しました。これらがすべて、ターゲットサービスに触れることなく済みました。

Trace ツールでのメッセージデータの表示

API プロキシの Trace ツールを使用すると、ヘッダー、変数、オブジェクトや、API プロキシのリクエストおよびレスポンスフローのレスポンス時間など、他の詳細を表示できます。さらに、API プロキシによって処理されるにつれて、リクエストまたはレスポンスがどのように変化するかを確認できます。

チュートリアルの前の方で、XML to JSON ポリシーが実行された後、Content-Type が application/xml から application/json に変わったことに触れました。この手順では、Trace ツールを使用して、この変化を表示し、初期状態のレスポンス本文 (XML) と変更後の本文 (JSON) を表示し、その他の興味深い詳細を確認します。

  1. API プロキシの「Develop」タブで、もう一度 Spike Arrest ポリシーの <Rate>1pm になるように編集し、プロキシを保存します。これにより、成功した API 呼び出しと失敗した (制限オーバーの) API 呼び出しの両方の確認が可能になります。
  2. API プロキシエディタで、 「Trace」タブをクリックします。
  3. 「Start Trace Session」をクリックします。
  4. Trace の「Transactions」ウィンドウに、少なくとも 1 つの 200 レスポンスと 1 つの 500 レスポンスが表示されるまで、cURL を使用して (または Web ブラウザで URL によって) 再び API プロキシを呼び出します。

    curl "http://{org-name}-test.apigee.net/hellopolicies"

  5. 「Stop Trace Session」をクリックします。
  6. 左側の「Transactions」ウィンドウの 200 トランザクションをクリックします。トランザクションマップの下のメインウィンドウにこの Trace の詳細が読み込まれ、リクエスト/レスポンス図が表示されます。Spike Arrest アイコンはリクエストフローにあり、XML to JSON アイコンはレスポンスフローにあります。
  7. フロー図で、レスポンス内の丸いアイコン (ただし、次の図に示されている、一番右のアイコン) をクリックします。

    「Phase Details」ウィンドウに、フロー内のそのポイントで利用できるデータが表示されます。このウィンドウをスクロールすると、HTTP レスポンスヘッダーや本文コンテンツが表示されます。
    • Content-Typeapplication/xml です。これは、ターゲットサービスからの通常のレスポンス形式です。
    • Body には、XML でのレスポンスコンテンツが表示されます。

  8. レスポンスフローで、「XML to JSON」アイコンをクリックします。「Phase Details」ウィンドウで、スクロールして以下を確認します。
    • Content-Type は、XML to JSON ポリシーによって application/json に変更されています。
    • Body は JSON 形式になっています。


  9. Now look at an error in Trace.

    Click the 500 transaction in the Transactions pane. In the main editor window, you see a flow diagram with items in the request only, including a Spike Arrest icon with a red exclamation point indicating an error.

    Click the small tube error icon to the right of the Spike Arrest icon, and look at the spike arrest violation details in the Phase Details pane.
    Spike arrest error

フロー図内の「Back」ボタンや「Next」ボタンをクリックして、フロー内のポイント間を移動し、Trace の詳細を確認できます。

Trace 全体を単一のドキュメントとして参照する場合は、「Download Trace Session」をクリックしてダウンロードします。

詳細については、「Trace ツールの使用」を参照してください。

 

Help or comments?