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.

バックエンド API リソースへの条件フローのマップ

API リソースと条件フローについて

RESTful バックエンドリソースと Edge プロキシリソース、または条件フローとの関係の概要については、次の短い動画を閲覧してください。

RESTful サービスは、API リソースの集合です。API リソースは、開発者が API を呼び出すことでアクセスできる複数のエンティティを識別する URI パスフラグメントです。例えば、気象情報と天気予報を提供しているサービスでは、バックエンドサービスで次の 2 つの API リソースが定義されている可能性があります。

  • http://mygreatweatherforecast.com/reports
  • http://mygreatweatherforecast.com/forecasts

API プロキシを作成する場合は、少なくともバックエンドサービスにマップするエイリアスベースの URL を作成します。次に例を示します。

バックエンドベースの URL 新規/同等の API プロキシの URL
http://mygreatweatherforecast.com http://{your_org}-{environment}.apigee.net/mygreatweatherforecast

どちらかのベース URL を使用すると、バックエンドへの API 呼び出しを行うことができます。ただし、API プロキシの URL を使用するとより興味深い処理を行うことができます。

API プロキシを使用すると、Edge が収集を開始する API アナリティクスに加えて、プロキシでは、バックエンドリソースにマップする条件フローも定義できます。基本的には、GET 呼び出しが /reports リソースに到着すると、Edge では何らかの処理を実行する必要があります。

次の図に、最終的には同じバックエンドにアクセスする 2 つの URL の動作の違いを示します。一方はプロキシを使用しないリソースの URL で、もう一方は同じバックエンドリソースへの条件フローを使用する Edge の API プロキシです。条件フローについては、以下に詳しく説明します。

API プロキシで特定のバックエンドリソースにマップする方法

バックエンドサービスのベース URL にマップされている API プロキシ URL を使用すると (プロキシを作成する場合)、前に述べた /reports リソース、 /forecasts リソースなどの特定のリソースに条件フローを追加できます。

呼び出しが /reports リソースまたは/forecasts リソースに到着すると、Edge で何らかの処理が実行される必要があるとします。Edge がそれらのリソースに対する呼び出しをリッスンしている必要があるため、この時点では、何を実行すべきかを Edge には指示していません。条件で実行する内容を指示します。Edge の API プロキシでは、/reports および/forecasts の条件フローを作成できます。概念的な目的のために、次の API プロキシの XML でそのような条件の内容を示します。

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
    </Flow>
    <Flow name="forecasts">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/forecasts") and (request.verb = "GET")</Condition>
    </Flow>
</Flows>

これらの条件では、そのフローに添付するポリシーを使用して、「GET リクエストが URL の /reports および /forecasts に到着したら、API 開発者が Edge に指示する内容を Edge がすべて実行する」ということを指示します。

以下は、条件が満たされたときに実行すべき内容を Edge に指示している例です。次の API プロキシの XML では、GET リクエストが https://yourorg-test.apigee.net/mygreatweatherforecast/reports に送信されたら、Edge ではレスポンスの「XML-to-JSON-1」ポリシーを実行します。

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response>
            <Step>
                <Name>XML-to-JSON-1</Name>
            </Step>
        </Response>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
</Flow>

デフォルトのフローに関する注意事項

これらのオプションの条件フローに加えて、各 API プロキシは 2 つのデフォルトのフローもあります。条件フローの前に実行される <PreFlow> と条件フローの後に実行される<PostFlow> です。 これらは、API プロキシに対して呼び出しが 行われたときにポリシーを実行する場合に役立ちます。例えば、アクセス対象のバックエンドリソースを問わず、すべての呼び出しでアプリの API キーを確認する場合、<PreFlow> に API キー検証ポリシーを配置できます。フローの詳細については、「フローの構成」を参照してください。

ベース URL とリソースを設計する際のベストプラクティスについては、「RESTful API の設計: 名詞は適切で、動詞は不適切」を参照してください。

バックエンドリソースに対する条件フローの作成

API プロキシでバックエンドリソースへの条件フローを定義することは完全に任意選択です。ただし、条件フローを使用すると、細かい管理と監視を適用することができます。

以下を実行することができます。

  • API モデルのセマンティクスを反映する方法での管理を適用する
  • 個々のリソースパス (URI) にポリシーとスクリプト動作を適用する
  • アナリティクスサービスのため細かなメトリックを収集する

例えば、バックエンドの /developers および /apps リソースに異なるタイプのロジックを適用する必要があるとします。

このためには、API プロキシで、/developers および /apps の 2 つの条件フローを追加します。

API プロキシエディタの「Navigator」ウィンドウの「Develop」ビューで、ProxyEndpoint のデフォルトの横の「+」アイコンをクリックします。

「New Conditional Flow」ウィンドウで、以下のキー構成を入力します:

  • フロー名: Developers
  • 条件タイプ: Path
  • パス: /developers

呼び出しが、URI の末尾に /developers がある状態でプロキシに送信された場合、この条件がトリガされます (そして、ポリシーが実行されます)。

次に、/app 用の条件フローを追加し、リクエストの URI と POST 動詞の両方で条件をトリガしたい場合を想定してみましょう。この構成には、以下の設定が関係します。

  • Flow Name: Apps
  • Condition Type: Path and Verb
  • Path: /apps
  • Verb: POST

呼び出しが、URI の末尾に /apps があり、POST 動詞がある状態でプロキシに送信された場合、この条件がトリガされます (そして、ポリシーが実行されます)。

「Navigator」ウィンドウに、Apps および Developers 用の新しいフローが表示されます。

いずれかのフローを選択して、API プロキシエディタのコードビューに条件フロー構成を表示します。

<Flow name="Apps">
    <Description>Developer apps registered in Developer Services</Description>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/apps") and (request.verb = "POST")</Condition>
</Flow>

お分かりのように、API リソースは受信リクエストの URI パスを評価する単なる条件フローです。(proxy.pathsuffix 変数では、ProxyEndpoint 構成で構成されている BasePath に続くリクエストの URI を識別します。)

定義した各 API リソースは、API プロキシの条件フローによって実装されます(「フローの構成」を参照してください)。

API プロキシをテスト環境に展開すると、次のリクエスト

http://{org_name}-test.apigee.net/{proxy_path}/apps

により、条件が true と評価され、このフローと関連付けられているすべてのポリシーが実行されます。

条件の作成

条件の作成の詳細については、「条件リファレンス」を参照してください。例えば、次の条件では Java の正規表現を使用して、末尾のスラッシュの有無を問わず (/apps または /apps/**)、/apps リソースに対して行われた呼び出しを認識します。

<Condition>(proxy.pathsuffix JavaRegex "/apps(/?)") and (request.verb = "POST")</Condition>

このタイプの条件の詳細については、次の Apigee コミュニティのスレッドを参照してください。

https://community.apigee.com/questions/4284/how-do-you-override-at-the-end-of-the-url-when-you.html

階層 URI のモデル化

場合によっては、階層的な API リソースを使用することがあります。例えば、開発者サービス API では、開発者に属しているすべてのアプリをリストする方法を提供します。URI パスは次のとおりです。

/developers/{developer_email}/apps

コレクションの各エンティティに対して一意の ID が生成されるリソースを使用している場合があります。これは、以下のような注釈が付きます。

/genus/:id/species

このパスは、次の 2 つの URI に同様に適用されます。

/genus/18904/species
/genus/17908/species

API リソースでこの構造を表すためには、ワイルドカードを使用できます。次に例を示します。

/developers/*/apps
/developers/*example.com/apps
/genus/*/species

これらのワイルドカードでは、階層 URI は API リソースとして適宜解決されます。

特に API の階層が深い場合、特定の URI フラグメント以下のすべての要素を解決する必要があります。このためには、リソース定義にワイルドカード (アスタリスク 2 個) を使用します。例えば、次の API リソースを定義したとします。
/developers/**

その API リソースにより次の URI のパスが解決されます。

/developers/{developer_email}/apps
/developers/{developer_email}/keys
/developers/{developer_email}/apps/{app_id}/keys

次に、条件フロー条件が API プロキシの定義ではどのように指定されるかを示します。

<Condition>(proxy.pathsuffix MatchesPath "/developers/**") and (request.verb = "POST")</Condition>

Help or comments?