您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。
任何應用程式程式設計模型都包含控制流程的方法。在 API Proxy 中,使用資料流即可完成。在流程中新增邏輯、條件陳述式、錯誤處理等項目。使用流程來控制當下發生的情況和時間。
資料流會沿著 API 要求處理路徑的順序依序完成,當您新增 Proxy 邏輯 (例如驗證 API 金鑰) 時,請將邏輯新增為資料流所指定序列中的步驟。定義條件以指定邏輯的執行時間和執行時間時,您可以將條件新增至流程。
以下流程設定範例會定義在驗證要求路徑以 /
結尾,且要求的 HTTP 動詞為 GET 時,VerifyKey 政策會執行流程。
<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 後端目標互動的選用程式碼 (如果有的話) (如果有的話)。
兩個端點都包含資料流,如下所述:
端點類型 | 說明 | 支援的流程 |
---|---|---|
Proxy 端點 | 包含最接近用戶端的 API Proxy 流程。提供邏輯,先讓用戶端在用戶端對要求執行動作,接著再處理用戶端的回應。 | PreFlow、條件式流程、PostFlow、PostClientFlow |
目標端點 | 包含最接近後端資源的 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 很適合用來記錄某些資料、傳送相關通知,以及轉換回應訊息格式等。
在以下範例中,SetSetHeaders 的 AssignMessage 政策會在 Apigee Edge 傳回回應給用戶端之前,設定回應訊息的標頭。
<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> ...
影片:請觀看這部短片,瞭解如何使用「4 分鐘影片開發人員簡介」(4MV4D) 系列中的「MessageLoggingF」政策建立 PostClientFlow。
詳情請參閱:
在資料流中新增邏輯
將邏輯新增至 Proxy 的流程時,您就能為 Proxy 的流程加入政策。如同流程 (依序執行,後面則是 Flow,然後是後續流程,如本主題所述) 執行。
以下流程設定參照三項政策 (在其 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,請參閱「使用 Trace 工具」。
處理流程中的錯誤
您可以在 API Proxy 中來自不同位置提高錯誤,包括資料流。
以下範例是目標端點中來自 PreFlow 的回應,也就是說,當從後端目標接收回應時,程式碼會立即執行。在此範例中,如果目標的回應數量不是 200 (成功),就會發出錯誤。
<PreFlow name="PreFlow"> <Response> <Step> <Name>RaiseFault</Name> <Condition>(response.status.code GreaterThan "200")</Condition> </Step> </Response> </PreFlow>
如要進一步瞭解如何處理錯誤,請參閱處理錯誤。