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

您目前查看的是 Apigee Edge 說明文件。
參閱 Apigee X說明文件。 資訊

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

流程是 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 在其他 Proxy 中設定的政策，例如：

<?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 就非常實用。

PreFlow 在 Proxy 端點中是非常適合用來驗證用戶端及限制用戶端流量的程式碼。在目標端點中，於開始準備將要求傳送至後端目標時，PreFlow 很適合用於準備傳送要求的第一步。

例如，通常不希望服務超出配額的用戶端。為支援這些需求，您可以在 PreFlow 區段中放置安全性和配額政策。這樣一來，您就不必擔心條件在後續條件式流程中無法評估。這個流程中的政策一律會先執行，再進行任何其他處理。

在以下範例中，系統會先執行 SpikeArrest 和配額政策，再將處理作業傳遞至條件式流程。

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

讓程式碼透過條件式流程有條件地執行

在預流程和後續流程之間，您可以使用有條件執行的流程。這可讓您設定多個邏輯序列，但只根據 Proxy 的狀態執行一個。如果您可以在 PreFlow 或 PostFlow 中執行所有邏輯，且不需要任何條件 (也就是只支援透過端點的單一路徑)，則條件式流程是選用的。

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

在這裡，只有在要求是 URI 模式為 /issue/** 的 GET 要求時 (/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 是在端點核心邏輯之後和端點處理完成之前執行動作的絕佳位置。在條件式流程和 PreFlow 之後執行 PostFlow。

PostFlow 是記錄部分資料、傳送發生事件的通知、轉換回應訊息格式等的絕佳位置。

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

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

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

PostClientFlow 可包含以下政策：

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

^* FlowCallout 政策只能呼叫符合 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) 一樣，流程中的內容也會依序執行。

以下流程設定範例參照三項政策，也就是在其他位置設定的政策。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 中的邏輯在要求之後的執行情況。這項工具會說明要求和回應之間的處理作業。並未具體說明預流程、條件流程和後流程之間的區別。

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

處理流程中的錯誤

您可以在 API Proxy 的各個位置 (包括資料流) 中觸發錯誤。

以下範例是目標端點中 PreFlow 的回應節，也就是在收到後端目標的回應時立即執行的程式碼。在本例中，如果目標的回應不是 200 (成功)，就會觸發錯誤。

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

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