您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
upsFault 政策可讓 API 開發人員啟動錯誤流程、在回應主體訊息中設定錯誤變數,以及設定適當的回應狀態碼。您也可以使用 riseFault 政策設定與錯誤相關的資料流變數,例如 fault.name
、fault.type
和 fault.category
。由於這些變數會顯示在數據分析資料和用於偵錯的路由器存取記錄檔中,因此請務必準確找出錯誤。
您可以使用 UpFault 政策將特定條件視為錯誤,即使 API Proxy 的其他政策或後端伺服器沒有實際發生的錯誤也一樣。舉例來說,如果您希望 Proxy 在每次後端回應主體包含 unavailable
字串時,將自訂錯誤訊息傳送至用戶端應用程式,您可以叫用 riseFault 政策,如以下程式碼片段所示:
<!-- /antipatterns/examples/raise-fault-conditions-1.xml --> <TargetEndpoint name="default"> ... <Response> <Step> <Name>RF-Service-Unavailable</Name> <Condition>(message.content Like "*unavailable*")</Condition> </Step> </Response> ...
LiftFault 政策名稱在
API Monitoring 中會顯示為 fault.name
,在 Analytics (分析) 和路由器存取記錄檔中會顯示為 x_apigee_fault_policy
。這有助於您輕鬆診斷錯誤原因。
反模式
在其他政策擲回錯誤後,在 FaultRules 中使用 IncreaseFault 政策
請參考以下範例,其中 API Proxy 流程中的 OAuthV2 政策失敗,並顯示 InvalidAccessToken
錯誤。失敗時,Edge 會將 fault.name
設為 InvalidAccessToken
,進入錯誤流程,然後執行任何已定義的 FaultRules。在 FaultRule 中,有一個名為 RaiseFault
的 riseFault 政策,會在發生 InvalidAccessToken
錯誤時傳送自訂錯誤回應。但是,如果在 FaultRule 中使用 IncreaseFault 政策,表示 fault.name
變數遭到覆寫,並遮蓋了失敗的實際原因。
<!-- /antipatterns/examples/raise-fault-conditions-2.xml --> <FaultRules> <FaultRule name="generic_raisefault"> <Step> <Name>RaiseFault</Name> <Condition>(fault.name equals "invalid_access_token") or (fault.name equals "InvalidAccessToken")</Condition> </Step> </FaultRule> </FaultRules>
在所有條件下在 FaultRule 中使用 IncreaseFault 政策
在以下範例中,如果 fault.name
不是 RaiseFault
,系統會執行名為 RaiseFault
的 riseFault 政策:
<!-- /antipatterns/examples/raise-fault-conditions-3.xml --> <FaultRules> <FaultRule name="fault_rule"> .... <Step> <Name>RaiseFault</Name> <Condition>!(fault.name equals "RaiseFault")</Condition> </Step> </FaultRule> </FaultRules>
如同第一個情境,系統會將 fault.name
、fault.code
和 fault.policy
主要錯誤變數覆寫為 riseFault 政策的名稱。這種行為幾乎無法判斷實際造成失敗的政策,而無法存取顯示失敗或重現問題的追蹤檔。
使用 riseFault 政策,在錯誤流程之外傳回 HTTP 2xx 回應。
在以下範例中,當要求動詞為 OPTIONS
時,名為 HandleOptionsRequest
的 riseFault 政策會執行:
<!-- /antipatterns/examples/raise-fault-conditions-4.xml --> <PreFlow name="PreFlow"> <Request> … <Step> <Name>HandleOptionsRequest</Name> <Condition>(request.verb Equals "OPTIONS")</Condition> </Step> … </PreFlow>
意圖是立即將回應傳回至 API 用戶端,而不處理其他政策。不過,這會導致數據分析資料產生誤導性質,因為錯誤變數會包含 riseFault 政策名稱,讓 Proxy 更難以偵錯。如要實作所需行為,正確的方式是在特殊條件下使用 Flows,如新增 CORS 支援所述。
影響程度
按照上述方式使用 upsFault 政策,會導致使用 GrowFault 政策的名稱覆寫金鑰錯誤變數,而非失敗政策的名稱。在 Analytics (分析) 和 NGINX 存取記錄中, x_apigee_fault_code
和 x_apigee_fault_policy
變數會遭到覆寫。在 API Monitoring 中,Fault Code
和 Fault Policy
遭到覆寫。這種行為將令人難以進行疑難排解,並判斷哪個政策是失敗的真正原因。
在下方 API Monitoring 的螢幕截圖中,您可以看到錯誤程式碼和錯誤政策覆寫為一般的 RaiseFault
值,因此無法從記錄檔判斷錯誤的根本原因:
最佳做法
當 Edge 政策提出錯誤,而您想要自訂錯誤回應訊息時,請使用 AssignMessage 或 JavaScript 政策,而不是 IncreaseFault 政策。
LiftFault 政策應在非錯誤流程中使用。也就是說,只有在政策或 API Proxy 的後端伺服器中未發生實際錯誤時,才需要使用 riseFault 將特定條件視為錯誤。舉例來說,您可以使用 riseFault 政策,指出必要的輸入參數缺少或含有不正確的語法。
如果在處理錯誤期間偵測錯誤,您也可以在錯誤規則中使用 深入分析資訊。例如,錯誤處理常式本身可能產生錯誤,而您想要使用 riseFault 發出訊號。