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

どのアプリケーション プログラミング モデルにも、処理のフローを制御する手段があります。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 プロキシのコードは、プロキシのクライアント(プロキシ エンドポイント)とやり取りするコードと、プロキシのバックエンド ターゲット(ターゲット エンドポイント)とやり取りするオプションのコード(存在する場合)の間で分けられています。

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

エンドポイント タイプ 説明 サポートされているフロー
ProxyEndpoint クライアントに最も近い API プロキシフローが含まれています。クライアントからのリクエストに対して最初に作用し、クライアントへのレスポンスに対して最後に作用する場所がロジックに提供されます。 PreFlow、条件フロー、PostFlow、PostClientFlow
TargetEndpoint バックエンド リソースに最も近い API プロキシフローが含まれています。バックエンド リソースに対するリクエストを準備し、バックエンド リソースからのレスポンスを処理する場所がロジックに提供されます。 PreFlow、条件フロー、PostFlow

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

HTTP サービスに到達するために、プロキシ エンドポイントを経由してバックエンドのターゲット エンドポイントに渡される HTTP クライアントからのリクエスト。各リクエストとレスポンス パネルには、PreFlow、条件付きフロー、PostFlow が表示されます。さらに、プロキシ エンドポイントとターゲット エンドポイントの例も示しています。

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

順序 フロータイプ 説明
1 PreFlow

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

ターゲット エンドポイントに PreFlow がある場合は、プロキシ エンドポイントの PostFlow の後に実行されます。

2 条件フロー

条件ロジック用の場所です。PreFlow の後かつ PostFlow の前に実行されます。

セグメントごとに 1 つの条件フロー(条件が true と評価された最初のフロー)だけが実行されます。つまり、条件フローは以下のそれぞれの一部として 1 つだけ実行できます。
  • ProxyEndpoint のリクエスト パイプライン
  • TargetEndpoint のリクエスト パイプライン
  • ProxyEndpoint のレスポンス パイプライン
  • TargetEndpoint のレスポンス パイプライン
3 PostFlow

データのログ記録、リクエストの処理中に何かが起こった場合の通知などに適した場所です。条件フローと PreFlow の後に実行されます。

プロキシ エンドポイントに PostFlow があり、ターゲット エンドポイントがある場合、プロキシ エンドポイントの PostFlow はターゲット エンドポイントの PreFlow の前に実行されます。

4 PostClientFlow(プロキシフローのみ) レスポンスがクライアントに返された後にメッセージをロギングするためのフロー。

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 ポリシーだけです。このポリシーをアタッチすると、PostClientFlow は実行される最後のフローになり、レスポンスがクライアントに送信された後に実行されます。

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

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

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

動画: Message Logging ポリシーを使用して PostClientFlow を作成する方法を示している、Four Minute Video For Developers(4MV4D)シリーズの短い動画をご覧ください。

詳細については、次をご覧ください。

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

プロキシにロジックを追加する場合、プロキシのフローにポリシーを追加することでロジックを追加できます。フローが順序通り(このトピックで説明しているように、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 コンソールでは、このポリシーのシーケンスは 1 行のアイコンとして表され、各アイコンはポリシーを表します。リクエストパスに表示されているアイコンは、Verify API Key、Remove API Key、Quota です。

フローのデバッグ

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

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

フローでのエラーの処理

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

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

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

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