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

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示します。

フローは API プロキシの基本構成要素です。フローでは、API プロキシがポリシーやコードを実行する順序を構成することで、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/**（/issue/ に最後のスラッシュに続く URI 内の任意のコードを付加）である 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 がレスポンスをクライアントに送信する前に、SetResponseHeaders という AssignMessage ポリシーでレスポンス メッセージのヘッダーを設定しています。

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

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

PostClientFlow には、次のポリシーのみを含めることができます。PostClientFlow では他のポリシーを使用できません。

• FlowCallout ポリシー^*
• MessageLogging ポリシー
• ServiceCallout ポリシー

^* FlowCallout ポリシーは、PostClientFlow に存在する基準を共有フロー自身が満たす共有フローのみ（たとえば、互換性のあるポリシーのみを含む）を呼び出すことができます。

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

PostClientFlow は最終的なロギングに適した場所です。また、レスポンス メッセージの開始と終了のタイムスタンプをログに記録することもできます。

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

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

詳細については、API プロキシ構成リファレンスをご覧ください。

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

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

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

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

フローのデバッグ

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

プロキシのデバッグについて詳しくは、Debug ツールの使用をご覧ください。

フローでのエラーの処理

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

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

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

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