您正在查看 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 的第一個流程。這表示您可以在下列各個項目中,分別執行一個條件式流程:
|
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 可包含下列政策:
* 流程呼叫政策只有在本身符合 PostClientFlow 中的條件時,才能呼叫共用流程 (也就是僅包含相容的政策)。
如果您加入 PostClientFlow,這是最後一個執行的流程,在回應傳送至用戶端後就會執行。
PostClientFlow 適用於最終記錄。此外,您也可以記錄回應訊息的開始和結束時間戳記。
以下是附加 MessageLogging 政策的 PostClientFlow 範例。
... <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <PostClientFlow> <Request/> <Response> <Step> <Name>Message-Logging-1</Name> </Step> </Response> </PostClientFlow> ...
影片:請觀看這部短片,瞭解如何使用 Four Minute Video For Developers (4MV4D) 系列的 MessageLogging 政策建立 PostClientFlow。
詳情請參閱:
在流程中新增邏輯
為 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>
如需進一步瞭解錯誤處理方法,請參閱「處理錯誤」。