控管 Proxy 與資料流的執行方式

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

任何應用程式程式設計模型都包含控制處理流程的方法。在 API Proxy 中，這項作業是透過流程完成。您可以在流程中新增邏輯、條件陳述式、錯誤處理等。你可以使用流程控制事件的發生時間和方式。

流程是 API 要求處理路徑中的連續階段。新增 Proxy 邏輯 (例如驗證 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 值用於在 Proxy 中納入以 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>

設計流程執行序列

您可以建構流程，讓邏輯沿著處理路徑以正確順序執行。

決定要在何處新增邏輯時，請先選擇要新增至 Proxy 端點或目標端點。API Proxy 會將程式碼分成兩類：與 Proxy 用戶端 (Proxy 端點) 互動的程式碼，以及與 Proxy 後端目標互動的程式碼 (如有) (目標端點)。

這兩個端點都包含流程，如下所述：

您可以使用 XML 設定流程，指定應執行的動作和順序。下圖說明流程在 Proxy 端點和目標端點中的排序方式：

Proxy 端點和目標端點各包含可依下列順序排列的流程：

使用 PreFlow 優先執行程式碼

如果您需要確保特定程式碼在任何其他事件發生前執行，PreFlow 就非常實用。

在 Proxy 端點中，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 之間，您可以設定有條件執行的流程。這可讓您設定多個邏輯序列，但只根據 Proxy 的狀態執行一個序列。如果可以在 PreFlow 或 PostFlow 中執行所有邏輯，且不需要任何條件 (換句話說，系統只支援透過端點的一條路徑)，則條件式流程為選用功能。

每個流程都會指定條件，測試不同的狀態值。這項作業會根據條件有效分支執行作業。舉例來說，您可能只希望在要求應用程式於行動裝置上執行時，才將 XML 轉換為 JSON。

在此，只有在要求是 GET 要求，且 URI 模式為 /issue/** (「/issue/」後方有任何內容) 時，才會強制執行配額限制。

<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 是執行動作的絕佳位置。條件式流程和 PreFlow 執行完畢後，就會執行 PostFlow。

PostFlow 非常適合記錄某些資料、傳送發生某件事的通知、轉換回應訊息格式等。

在下列範例中，名為 SetResponseHeaders 的 AssignMessage 政策會在 Apigee Edge 將回應傳回給用戶端之前，設定回應訊息的標頭。

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

在用戶端收到 Proxy 的回應後，使用 PostClientFlow 執行程式碼

PostClientFlow 可包含下列政策：

• 摘要額外資訊政策
• FlowCallout 政策^*
• MessageLogging 政策
• ServiceCallout 政策

^* FlowCallout 政策只能呼叫符合 PostClientFlow 條件的共用流程 (即只包含相容的政策)。

如果包含 PostClientFlow，系統會在傳送回應給用戶端後執行，因此 PostClientFlow 會是最後執行的流程。

PostClientFlow 適合用於最終記錄。此外，你也可以記錄回覆訊息的開始和結束時間戳記。

以下是附加 MessageLogging 政策的 PostClientFlow 範例。

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

如需詳細資訊，請參閱：

• API Proxy 設定參考資料
• 教學課程：Apigee Edge - Post Client Flow 社群文章

在流程中新增邏輯

如要為 Proxy 新增邏輯，請在 Proxy 的流程中新增政策。如同流程會依序執行 (如本主題所述，依序為 PreFlow、Flow 和 PostFlow)，流程內容也會依序執行。

下列範例流程設定會參照三項政策 (在各自的 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 控制台會以一列圖示呈現這組政策，每個圖示代表一項政策。

偵錯流程

Apigee Edge Trace 工具提供圖形化方式，讓您瞭解 API Proxy 中的邏輯在收到要求後如何執行。這項工具會說明要求和回應之間的處理程序。但並未具體說明 PreFlow、條件式流程和 PostFlow 之間的區隔。

如要進一步瞭解追蹤 Proxy，請參閱「使用追蹤工具」。

處理流程中的錯誤

您可以在 API Proxy 的多個位置 (包括流程) 引發錯誤。

以下範例是目標端點中 PreFlow 的回應節。換句話說，這是指從後端目標收到回應後，會立即執行的程式碼。在這個範例中，如果目標的回應不是 200 (成功)，就會引發錯誤。

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

如要進一步瞭解如何處理錯誤，請參閱「處理錯誤」。