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

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

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

使用 PromoteFault 政策可將特定條件視為錯誤，即使實際錯誤 未在其他政策或 API Proxy 的後端伺服器中發生。舉例來說 讓 Proxy 在每次後端回應時，將自訂錯誤訊息傳送至用戶端應用程式 主體包含 unavailable 字串，所以您可以叫用 flaFault 政策，如下所示： 如以下程式碼片段所示： 

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

flaFault 政策的名稱在 中會顯示為 fault.name API 監控功能，以及 Analytics 和路由器存取記錄檔中的 x_apigee_fault_policy。 以便輕鬆診斷錯誤原因。

反模式

在某項政策擲回錯誤後，於 FaultRules 中使用 PromoteFault 政策

請參考以下範例，瞭解 API Proxy 流程中的 OAuthV2 政策失敗，並顯示 InvalidAccessToken 錯誤。失敗時，Edge 會將 fault.name 設為 InvalidAccessToken，然後輸入 錯誤流程，然後執行任何已定義的 FaultRules。FaultRule 中有一個 flaFault 政策 RaiseFault，每當有 InvalidAccessToken 時，會傳送自訂錯誤回應 錯誤。不過，在 FaultRule 中使用 PromoteFault 政策表示 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 中使用 上述 flaFault 政策

在以下範例中，如果 fault.name 定義了 RaiseFault 的 PromoteFault 政策， 不是 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 皆以 PromoteFault 政策的名稱覆寫。這個行為會使 在未存取追蹤記錄的情況下，幾乎無法判斷哪一項政策實際上是造成失敗的原因 檔案，其中顯示錯誤或重現問題。

使用 PromoteFault 政策傳回錯誤流程以外的 HTTP 2xx 回應。

在下列範例中，會執行名為 HandleOptionsRequest 的 上述 flaFault 政策，會在下列時機執行： 要求動詞為 OPTIONS： 

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

意圖是在不處理其他政策的情況下，立即將回應傳回 API 用戶端。 不過，由於錯誤變數會包含 flaFault 政策的名稱，讓 Proxy 更難以偵錯。正確的實作方式 因此，想要搭配特殊條件使用 Flows，如 新增 CORS 支援。

影響

按照上述方式使用 PromoteFault 政策會導致使用 將失敗政策的名稱改為上述名稱遞增。在 Analytics 和 NGINX 存取記錄中 x_apigee_fault_code 和 x_apigee_fault_policy 變數 都會遭到覆寫在 API Monitoring 中，Fault Code 和 Fault Policy 是否遭到覆寫這種行為導致難以疑難排解 判斷失敗的真正原因為何。

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

最佳做法

如果 Edge 政策提出錯誤，而您想要自訂錯誤回應訊息， 使用 AssignMessage 或 JavaScript 政策，而非 PromoteFault 政策。

PromoteFault 政策應用於非錯誤流程。也就是只使用 上述方法 視為錯誤值，即使政策或後端伺服器沒有實際錯誤也一樣 API Proxy 後端舉例來說，您可以使用 PromoteFault 政策指明必須輸入 參數遺失或語法不正確。

如果在錯誤規則的處理期間偵測到錯誤，您也可以在錯誤規則中使用 PromoteFault 錯誤例如，錯誤處理常式本身可能會引發錯誤，而您想使用 上述方法提報錯誤。

延伸閱讀