反模式：在不當情況下使用 IncreaseFault 政策

您正在查看 Apigee 和 Apigee Hybrid 說明文件。
查看 Apigee Edge 說明文件。

RaiseFault 政策可讓 API 開發人員啟動錯誤流程、在回應主體訊息中設定錯誤變數，以及設定適當的回應狀態碼。您也可以使用 RaiseFault 政策來設定與錯誤相關的流程變數，例如 fault.name、fault.type 和 fault.category。由於這些變數會顯示在用於偵錯的數據分析資料和 Router 存取記錄中，因此請務必準確找出錯誤。

您可以使用 RaiseFault 政策，將特定情況視為錯誤，即使其他政策或 API 代理程式後端伺服器並未發生實際錯誤，也一樣。舉例來說，如果您希望代理程式在後端回應主體包含字串 unavailable 時，向用戶端應用程式傳送自訂錯誤訊息，則可以呼叫 RaiseFault 政策，如以下程式碼片段所示：

<!-- /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>
...

在 API 監控中，RaiseFault 政策的名稱會顯示為 fault.name，在 Analytics 和 Router 存取記錄中則會顯示為 x_apigee_fault_policy。這有助於輕鬆診斷錯誤原因。

反模式

在另一個政策已擲回錯誤後，使用 FaultRules 中的 RaiseFault 政策

請參考下列範例，其中 API Proxy 流程中的 OAuthV2 政策因 InvalidAccessToken 錯誤而失敗。發生失敗時，Apigee 會將 fault.name 設為 InvalidAccessToken，進入錯誤流程，並執行任何定義的 FaultRules。在 FaultRule 中，有一個名為 RaiseFault 的 RaiseFault 政策，可在發生 InvalidAccessToken 錯誤時傳送自訂錯誤回應。不過，在 FaultRule 中使用 RaiseFault 政策，就表示 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 中使用 RaiseFault 政策

在以下範例中，如果 fault.name 不是 RaiseFault，就會執行名為 RaiseFault 的 RaiseFault 政策：

<!-- /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 會被 RaiseFault 政策名稱覆寫。由於這項行為，除非您存取顯示失敗情形的追蹤記錄檔或重現問題，否則幾乎無法判斷哪項政策實際上造成失敗。

使用 RaiseFault 政策，在錯誤流程之外傳回 HTTP 2xx 回應。

在下列範例中，當要求動詞為 OPTIONS 時，系統會執行名為 HandleOptionsRequest 的 RaiseFault 政策：

<!-- /antipatterns/examples/raise-fault-conditions-4.xml  -->
<PreFlow name="PreFlow">
    <Request>
        …
        <Step>
            <Name>HandleOptionsRequest</Name>
            <Condition>(request.verb Equals "OPTIONS")</Condition>
        </Step>
        …
</PreFlow>

意圖是立即將回應傳回給 API 用戶端，而不會處理其他政策。不過，這會導致錯誤分析資料，因為錯誤變數會包含 RaiseFault 政策的名稱，導致代理程式更難進行偵錯。如要實作所需行為，正確做法是使用具有特殊條件的流程，如「新增 CORS 支援」一文所述。

影響

依上述方式使用 RaiseFault 政策，會導致系統以 RaiseFault 政策的名稱覆寫主要錯誤變數，而非失敗政策的名稱。在 Analytics 和 NGINX 存取記錄中， x_apigee_fault_code 和 x_apigee_fault_policy 變數會遭到覆寫。在 API 監控中，Fault Code 和 Fault Policy 會遭到覆寫。這項行為會導致您難以進行疑難排解，並判斷哪項政策是導致失敗的真正原因。

在下方 API 監控的螢幕截圖中，您可以看到錯誤代碼和錯誤政策已覆寫為一般 RaiseFault 值，因此無法從記錄中判斷失敗的根本原因：

待定

最佳做法

當 Apigee 政策引發錯誤時，如果您想自訂錯誤回應訊息，請使用 AssignMessage 或 JavaScript 政策，而非 RaiseFault 政策。

RaiseFault 政策應用於非錯誤流程中。也就是說，即使政策或 API Proxy 的後端伺服器並未發生實際錯誤，也只需使用 RaiseFault 將特定情況視為錯誤。舉例來說，您可以使用 RaiseFault 政策，指出缺少必要輸入參數或語法不正確。

如果您想在處理錯誤時偵測錯誤，也可以在錯誤規則中使用 RaiseFault。舉例來說，錯誤處理程序本身可能會導致您想要使用 RaiseFault 發出信號的錯誤。

延伸閱讀