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

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

任何應用程式程式設計模型都提供了控制處理流程的方法。在 API Proxy 中，則會使用流程。如要流程新增邏輯、條件陳述式、錯誤處理等項目，您可以使用流程來控制情況和時間。

資料流是 API 要求處理路徑中的後續階段。當您新增 Proxy 邏輯 (例如驗證 API 金鑰) 時，必須將邏輯新增為流程指定的序列中的步驟。定義條件以指定是否執行邏輯，以及執行邏輯時，您可以在資料流中新增條件。

下列流程設定範例定義了當傳入的要求路徑以 / 結尾，且要求的 HTTP 動詞為 GET 時，if要執行 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 的後端目標 (如果有的話) 互動的選用程式碼 (如果有的話) 之間，分配程式碼。

這兩個端點都含有資料流，如下所述：

端點類型	說明	支援資料流
ProxyEndpoint	包含最靠近用戶端的 API Proxy 流程。提供邏輯位置，用來處理用戶端要求，最後回應用戶端的回應。	PreFlow、條件式流程、PostFlow、PostClientFlow
TargetEndpoint	包含最接近後端資源的 API Proxy 流程。提供邏輯位置，以便準備要求，以及處理後端資源的回應。	PreFlow、條件式流程、PostFlow

您需要使用 XML 設定流程，藉此指定後續動作和順序。下圖顯示在 Proxy 端點和目標端點內，資料流的排序方式：

每個 Proxy 端點和目標端點都含有按照下列順序排列的流程：

位置	流程類型	說明
1	PreFlow	如要確保特定程式碼在發生其他情況之前就先執行，此屬性就非常實用。 如果 PreFlow 位於目標端點，就會在 Proxy 端點的 PostFlow 之後執行。
2	條件式流程	條件式邏輯的位置。在 PreFlow 之後和 PostFlow 之前執行。 每個區隔只會執行一個條件式流程，也就是條件評估為 true 的第一個流程。這表示您可以在下列各個項目中，分別執行一個條件式流程： ProxyEndpoint 的要求管道 TargetEndpoint 的要求管道 ProxyEndpoint 的回應管道 TargetEndpoint 的回應管道
3	PostFlow	需要記錄資料、傳送處理要求期間發生的通知等的絕佳位置。在條件式流程和 PreFlow 後執行。 如果 PostFlow 位於 Proxy 端點，且有目標端點，則 Proxy 端點 PostFlow 會在目標端點 PreFlow 之前執行。
4	PostClientFlow (僅限 Proxy 流程)	將回應傳回給用戶端後記錄訊息的流程。

讓程式碼先使用 PreFlow 執行

如果您需要確保特定程式碼在發生其他狀況之前就先執行，則 PreFlow 非常實用。

在 Proxy 端點中，PreFlow 非常適合用於驗證用戶端，並限制來自用戶端的流量。在目標端點中，系統會開始準備傳送要求至後端目標，而 PreFlow 適用於準備傳送要求的第一步。

舉例來說，您通常不希望為超出其配額的用戶端提供服務。為支援這些需求，您可以在 PreFlow 區段中加入安全性和配額政策。如此一來，您不必擔心在後續的條件式流程中無法評估的條件。這個流程中的政策一律會在進行其他處理程序之前執行。

在以下範例中，系統會先執行 SpikeArrest 和配額政策，然後再處理傳送至條件式流程的流程。

<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/，位於最後正斜線後的任何 URI) 時，系統才會強制執行配額限制。

<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 收到 Proxy 回應後執行

PostClientFlow 可包含下列政策：

• 額外資訊摘要政策
• 流程摘要政策^*
• MessageLogging 政策
• 服務摘要政策

^* 流程呼叫政策只有在本身符合 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 - 用戶端流程後社群文章

在流程中新增邏輯

為 Proxy 新增邏輯時，您可以在 Proxy 流程中新增政策。就像按照本主題所述，依序執行 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>

如需進一步瞭解錯誤處理方法，請參閱「處理錯誤」。