使用流程控管 API Proxy

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

流程是 API Proxy 的基本構成要素。您可以透過流程設定 API Proxy 執行政策和程式碼的順序，藉此編寫 API 的行為。

流程是 API 要求處理路徑中的連續階段。新增代理邏輯 (例如驗證 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 值可用於在 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 端點和目標端點中依序排序流程：

代理端點和目標端點各自包含流程，您可以按照以下順序安排這些流程：

先透過 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 是記錄部分資料、傳送發生事件的通知、轉換回應訊息格式等的絕佳位置。

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

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

在用戶端透過 PostClientFlow 收到您的 Proxy 回應後執行程式碼

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

偵錯流程

偵錯工具提供圖形化方式，讓您瞭解 API 代理程式在收到要求後如何執行邏輯。這項工具會說明要求和回應之間的處理作業。並未具體說明預流程、條件式流程和後續流程之間的區別。

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

處理流程中的錯誤

您可以在 API Proxy 的各個位置 (包括工作流程) 中提出錯誤。

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

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

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