フローによるプロキシの実行の制御

どのアプリケーション プログラミング モデルにも、処理のフローを制御する手段があります。API プロキシではフローを使用して制御できます。フローには、ロジック、条件ステートメント、エラー処理などを追加できます。フローを使用して、何をどの時点で行うかを制御できます。

フローは、API リクエストの処理パスに沿った連続したステージです。API キーの検証などのロジックをプロキシに追加する場合、フローで指定されているシーケンス内のステップとしてそのロジックを追加します。ロジックを実行するかどうかと、どのタイミングで実行するかを指定するための条件を定義する場合は、フローに条件を追加します。

次のフロー構成の例は、受信リクエストのパスの末尾が / であり、そのリクエストの HTTP 動詞が GET である場合に、VerifyAPIKey ポリシーが実行されるフローを定義しています。

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

このフローの <Name> 要素の Verify-API-Key という値は、次のような XML プロキシ内の別の場所で構成されているポリシーを含める働きをします。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

フロー実行シーケンスの設計

処理パスに沿って適切なシーケンスでロジックが実行されるように、フローを構築します。

ロジックをどこに追加するかを判断する場合、プロキシ エンドポイントとターゲット エンドポイントのどちらに追加するかを最初に選択します。API プロキシのコードは、プロキシのクライアント（プロキシ エンドポイント）とやり取りするコードと、プロキシのバックエンド ターゲット（ターゲット エンドポイント）とやり取りするオプションのコード（存在する場合）の間で分けられています。

以下に説明するように、どちらのエンドポイントにもフローが含まれています。

フローは、何をどのような順序で行うかを指定する XML を使用して構成します。次の図は、プロキシ エンドポイント内とターゲット エンドポイント内でフローがどのように連続的に順序付けされているかを示しています。

プロキシ エンドポイントとターゲット エンドポイントにはそれぞれ、次の順序でユーザーが配置できるフローがあります。

PreFlow による最初のコード実行

PreFlow は、他の処理が実行される前に特定のコードを確実に実行する必要がある場合に役立ちます。

プロキシ エンドポイントの PreFlow は、クライアントを認証するコードや、クライアントからのトラフィックを制限するコードに最適な場所です。バックエンド ターゲットへのリクエストを送信する準備を開始するターゲット エンドポイントの PreFlow は、リクエストを送信する準備を行う最初のステップとして最適です。

たとえば、割り当てを超えているクライアントに対して通常はサービスを提供することを望みません。このような要件をサポートするには、セキュリティ ポリシーと割り当てポリシーを PreFlow セグメントに配置します。これにより、後続の条件付きフローで条件の評価が失敗することを気にする必要がなくなります。このフローでのポリシーは必ず、他の処理が行われる前に実行されます。

次の例では、処理が条件付きフローに渡される前に SpikeArrest ポリシーと Quota ポリシーが実行されます。

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

条件付きフローによる条件付きのコード実行

PreFlow と PostFlow の間に、条件付きで実行されるフローを配置できます。このフローにより、ロジックの複数のシーケンスを構成できますが、プロキシの状態に基づいて 1 つのロジックだけが実行されます。PreFlow と PostFlow ですべてのロジックを実行できる場合や、条件が不要な場合（つまり、エンドポイントで 1 つのパスだけがサポートされている）、条件付きフローは省略できます。

各フローでは、異なる状態値を調べる条件を指定します。これにより、条件に基づいて実行が効果的に分岐されます。たとえば、リクエスト元のアプリがモバイル デバイスで実行されている場合にのみ、XML を JSON に変換できます。

次の例では、リクエストが、URI パターン /issue/**（URI で /issue/ の最後のスラッシュの後に何かが続いている）に一致する GET リクエストである場合にのみ、割り当て制限が適用されています。

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

フロー変数を使用して条件を指定できます。条件での変数の使用について詳しくは、フロー変数での条件をご覧ください。

条件でのパターン マッチングの使用例については、パターン マッチングをご覧ください。

コアロジックの後の PostFlow によるコード実行

PostFlow は、エンドポイントのコアロジックの後、かつエンドポイントでの処理が完了する前に行うアクションを配置するのに最適です。PostFlow は条件付きフローと PreFlow の後に実行されます。

PostFlow は、データのログ記録、何かが起きた場合の通知の送信、レスポンス メッセージのフォーマット変換などに適しています。

次の例では、Apigee Edge がレスポンスをクライアントに送信する前に、SetResponseHeaders という AssignMessage ポリシーでレスポンス メッセージのヘッダーを設定しています。

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

クライアントがプロキシのレスポンスを受信した後の PostClientFlow によるコード実行

PostClientFlow に含めることができるのは MessageLogging ポリシーと ExtensionCallout ポリシーだけです。このポリシーをアタッチすると、PostClientFlow は実行される最後のフローになり、レスポンスがクライアントに送信された後に実行されます。

PostClientFlow は最終的なロギングに適した場所です。また、レスポンス メッセージの開始時刻と終了時刻の間の時間間隔をロギングすることもできます。client.sent.start.timestamp と client.sent.end.timestamp の変数値は、レスポンスが送信されるまで計算されません。

Message Logging ポリシーが接続されている PostClientFlow の例を次に示します。

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

関連ページ

• API プロキシ構成リファレンス
• チュートリアル: Apigee Edge - Post Client Flow のコミュニティの記事

フローへのロジックの追加

プロキシにロジックを追加する場合、プロキシのフローにポリシーを追加することでロジックを追加できます。フローが順序通り（このトピックで説明しているように、PreFlow、条件付きフロー、PostFlow の順）に実行されるのと同様に、フローのコンテンツは順序通りに実行されます。

次のフロー構成の例では、3 つのポリシー（別の XML ファイルのどこかで構成されている）を参照しています。Verify-API-Key で参照されているポリシー、Remove-API-Key で参照されているポリシー、Quota で参照されているポリシーの順序で実行されます。

<Flow name="Get Food Cart Menus">
    <Description>Get Food Cart Menus</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
        <Step>
            <Name>Remove-API-Key</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Apigee Edge コンソールでは、このポリシーのシーケンスは 1 行のアイコンとして表され、各アイコンはポリシーを表します。

フローのデバッグ

Apigee Edge Trace ツールを使用すると、リクエストに続いて API プロキシ内のロジックがどのように実行されるかをグラフィカルに確認できます。このツールはリクエストとレスポンスの間の処理を図示します。その図では、PreFlow、条件付きフロー、PostFlow の間は明確には分離されていません。

プロキシのトレースの詳細については、Trace ツールの使用をご覧ください。

フローでのエラーの処理

フローからも含めて、API プロキシのさまざまな場所からエラーを発生させることができます。

次の例は、ターゲット エンドポイントの PreFlow からのレスポンス スタンザです。つまり、バックエンド ターゲットからレスポンスを受信した直後に実行されるコードです。この例では、ターゲットからのレスポンスが 200（成功）でない場合にエラーが発生します。

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

エラー処理について詳しくは、エラーの処理をご覧ください。