本頁面由 Cloud Translation API 翻譯而成。

使用流程控管 API Proxy

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

流程是 API Proxy 的基本建構區塊。您可以透過流程設定 API Proxy 執行的政策和程式碼順序，藉此設定 API 的運作方式。

流程是 API 要求處理路徑中的連續階段。新增 Proxy 邏輯 (例如驗證 API 金鑰) 時，請將邏輯新增為流程指定序列中的步驟。定義條件來指定是否及何時執行邏輯時，請將條件新增至流程。

下列流程設定範例定義的流程中，VerifyAPIKey 政策會在傳入要求路徑結尾為 / 且要求 HTTP 動詞為 GET 時執行。

<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>

設計流程執行序列

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

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

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

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

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

HTTP 用戶端的要求會通過 Proxy 端點，傳送至後端的 TargetEndpoint，最終抵達 HTTP 服務。每個要求和回應面板都會顯示前置流程、條件流程和後置流程。此外，我們也提供 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 和 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/** (URI 中最後一個正斜線後方有任何內容) 時，才會強制執行配額限制。/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 是在端點核心邏輯之後，以及端點處理完成之前執行動作的絕佳位置。PostFlow 會在條件流程和 PreFlow 之後執行。

PostFlow 是記錄某些資料、傳送發生某件事的通知、轉換回應訊息格式等的好地方。

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

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

在用戶端收到代理伺服器的回應後，使用 PostClientFlow 執行程式碼

PostClientFlow 只能包含下列政策。PostClientFlow 中無法使用其他政策：

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

如果包含 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 Proxy 設定參考資料。

在流程中新增邏輯

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

下列範例流程設定會參照三項政策 (在各自的 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>

注意：在上述程式碼中，路徑條件 (proxy.pathsuffix MatchesPath "/") 一律為 true，因為系統一律會比對 "/"。因此，您可以從「Condition」元素中移除該條件，並只使用動詞條件：

    <Condition>request.verb = "GET"</Condition>

偵錯流程

偵錯工具提供圖形化方式，讓您查看 API 代理程式中的邏輯在要求後如何執行。這項工具會說明要求和回應之間的處理程序。但並未具體說明 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>

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