處理錯誤

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

當 API Proxy 處理應用程式發出的要求時，可能會發生許多錯誤狀況。適用對象 例如，API Proxy 在與後端服務通訊時可能會遇到網路問題 應用程式可能會顯示過期的憑證，要求訊息可能也未正確設定格式， 保持開啟。

在用戶端應用程式呼叫 API Proxy 時發生錯誤時，系統會將錯誤訊息傳回 用戶端。根據預設，用戶端會收到通常不含詳細資料的隱密錯誤訊息，或 指引。但如果您想以更實用的自訂訊息取代預設錯誤訊息， 您甚至必須設定自訂錯誤 以及 Edge 中處理方式

此外，透過自訂錯誤處理功能，您也可以新增訊息記錄等功能 錯誤。

在我們討論將自訂錯誤處理機制導入 API Proxy 之前，建議您 瞭解發生錯誤的原因，以及 API Proxy 如何回應這些錯誤。

影片

請觀看以下影片，進一步瞭解錯誤處理方式。

影片 說明
簡介： 錯誤處理和錯誤流程 瞭解錯誤處理方式，以及 API Proxy 發生錯誤時會發生什麼事。
處理錯誤 錯誤規則 瞭解如何使用錯誤規則處理錯誤。
調高自訂值 使用 flaFault 政策來處理錯誤 在 API 執行階段使用 PromoteFault 政策引發自訂錯誤。
定義錯誤 API Proxy 與目標端點中的規則 在 API Proxy 和目標端點中定義錯誤規則，並瞭解 差異在於
瞭解 錯誤規則的執行順序 瞭解 API Proxy 和目標中錯誤規則的執行順序 端點。
定義預設 錯誤規則 定義預設錯誤規則來處理 API 中的一般錯誤。

錯誤發生方式

首先，我們會簡單說明會「如何」發生。瞭解錯誤發生的原因有助於規劃 在要導入自訂錯誤處理的不同情況中。

自動錯誤

在下列情況中，API Proxy 會自動擲回錯誤：

  • 政策會擲回錯誤。舉例來說，如果 API 呼叫傳送過期的金鑰， VerifyAPIKey 政策會自動擲回錯誤。或者 API 呼叫次數 超過特定限制時，配額政策或 SpikeArrest 政策會發生錯誤。 (請參閱政策錯誤參考資料， 錯誤政策可能擲回的類型)。
  • API Proxy 訊息流程發生問題，例如轉送錯誤。
  • 導致後端發生錯誤，例如因通訊協定層級故障而導致 HTTP 錯誤，以及傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 錯誤或無法使用的目標服務
  • 發生系統層級的故障，例如記憶體不足例外狀況。

如要進一步瞭解這些錯誤，請參閱本主題中的錯誤分類。

自訂錯誤

在未自動發生錯誤的情況下，您可能需要擲回自訂錯誤。的 例如，如果回應包含「unavailable」一詞，或 HTTP 狀態碼大小較大 201 年。方法很簡單，只要在 執行 API Proxy 流程

您可以對 API Proxy 流程新增 PromoteFault 政策，做法和執行任何其他政策相同。於 以下 Proxy 設定範例，Raise-Fault-1 政策已附加至 TargetEndpoint 回應。如果「無法使用」字樣回應 服務後，RAault 政策會執行並擲回錯誤。

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

這只是示範，您可以擲回自訂錯誤。接下來 FaultRules vs. 上述 flaFault 政策中的 PromoteFault 政策 專區。

如需更多範例，請參閱 Apigee 社群論壇中的貼文：

API Proxy 發生錯誤時的處理方式

Proxy 擲回錯誤時的情形如下：

結束 Proxy 管道

無論 API Proxy 發生錯誤的原因為何，系統都會結束一般流程管道 ，並將錯誤訊息傳回用戶端應用程式。API Proxy 進入 錯誤狀態，無法將處理程序傳回一般流程管道。

舉例來說，假設某個 API Proxy 在 ProxyEndpoint 中具有下列順序的政策 要求：

  1. 驗證 API 金鑰
  2. 配額
  3. 從 JSON 到 XML

如果 API 金鑰驗證期間發生錯誤，API Proxy 就會進入錯誤狀態。 未執行配額和 JSON 到 XML 政策，Proxy 不會繼續執行 TargetEndpoint， 並將錯誤訊息傳回用戶端應用程式。

檢查 FaultRules

在錯誤狀態中，API Proxy 也會檢查是否出現下列情況 (依序) 將預設錯誤訊息傳回用戶端應用程式之前，請先選取 API Proxy 設定：

  1. <FaultRules> 區段，其中包含 會根據您 定義。
  2. <DefaultFaultRule> 區段，用於觸發預設值 錯誤訊息：
    • 未定義任何<FaultRules>。
    • 未執行任何現有 <FaultRules>。
    • <AlwaysEnforce> 元素已設為 true。

基本上，API Proxy 可讓您傳回自訂的錯誤訊息 觸發其他邏輯如果 Proxy 找不到這些部分，或是這些部分不存在，但沒有任何自訂 fault 已觸發，Proxy 會傳送自己的 Edge 產生的預設訊息。

簡易錯誤處理範例

首先從簡單的範例開始，也就是對 API Proxy 的呼叫並未包含必要的 API 鍵。根據預設，系統會將下列回應傳回用戶端應用程式：

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

您的 API 使用者或許可以找出錯誤訊息，但可能無法。許多預設選項 錯誤更細微且難以分辨。

API 開發人員當然可以根據 無論是 iOS 應用程式開發人員或內部測試，最終都會收到錯誤訊息 群組，以有各自的錯誤訊息格式要求。

以下是如何建立自訂錯誤訊息來處理這項錯誤的基本範例。這個 需要 1) 定義自訂訊息的政策，以及 2) 執行政策的 FaultRule 當 Proxy 進入錯誤狀態時。

1. 建立政策 定義自訂訊息

首先，請建立定義自訂錯誤訊息的政策。您可以使用任何類型的政策 例如 AssignMessage 政策，您可以設定酬載和選用的 HTTP 標頭，例如 狀態碼 以及原因語句「指派訊息」功能相當適合用於這類用途。可讓您控制訊息酬載 以及設定其他 HTTP 原因詞組，並新增 HTTP 標頭。

請勿在 API Proxy 的任何流程中附加政策。只是單純存在於 Proxy 軟體包如要在管理 UI Proxy 編輯器中執行這項操作，請前往「開發」分頁，然後在 導覽窗格，按一下政策列上的 + 圖示。

這可以讓您建立政策，而不必附加至 API Proxy 的流程。政策 未附加至任何流程的標記會標記為「卸離」「政策」清單中的圖示 。

以下是 AssignMessage 政策的範例：

  • 傳回 JSON 訊息。
  • 設定 HTTP 狀態碼 (911)，這是顯然不存在的狀態碼 說明您可以的靈活性)。狀態碼會顯示在 HTTP 標頭中。
  • 設定 HTTP 原因詞組 (取代預設的「未經授權」原因詞組)。 缺少 API 金鑰錯誤)。在 HTTP 中，狀態碼旁邊會顯示原因詞組 標題。
  • 建立並填入名為 invalidKey 的新 HTTP 標頭。
<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

執行這項政策時，對用戶端應用程式的回應會如下所示。 請將其與稍早顯示的預設回應進行比較。

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

沒錯，這有點傻，但畫面中卻顯示出無限可能。至少現在是開發人員 收到訊息，知道他們忘了加入 API 金鑰做為查詢參數。

但這項政策的執行方式為何？下一部分說明瞭自己。

2. 建立 &lt;FaultRule&gt;觸發政策的

在以下頻道的 <ProxyEndpoint> 或 <TargetEndpoint> 部分中： 因此請新增一個 <FaultRules> XML 區塊，其中包含一個 或多個個別 <FaultRule> 版面。每個 FaultRule 都代表不同的 處理錯誤在這個簡單的範例中，我們僅使用一個 FaultRule 來說明 模型的構成、

您應該一併新增 <DefaultFaultRule> 來提供自訂的一般錯誤 訊息。

範例

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

重點：

  • FaultRules 是在 ProxyEndpoint 中定義。這很重要，深入瞭解 ProxyEndpoint 中的 FaultRules 和稍後的 TargetEndpoint 部署。
  • <Name>：要執行的政策名稱。名稱 來自政策在父項元素上的 name 屬性，如 政策範例

  • <Condition> - 邊緣評估條件和 只有在條件為 true 時才會執行政策。如果有多個 FaultRules 的值為 true，Edge 會執行第一個結果為 true。(重要事項： FaultRules 的評估順序 (由上至下或由上至頂端) 有所不同 TargetEndpoint 和 ProxyEndpoint，如多個 FaultRules 和執行邏輯」一節)。如果沒有包含條件，FultRule 會自動設為 true但這不是最佳做法。每個 FaultRule 都應有專屬的 值。

  • <DefaultFaultRule> - 如果沒有任何自訂 FaultRule 系統會執行 <DefaultFaultRule>，傳送較通用的 ，而不是由 Edge 生成的簡訊預設訊息。A 罩杯 <DefaultFaultRule> 也可以擁有 <Condition>，但在 大部分的情況都不會納入，因為您希望系統在任何最後執行時，就執行任何動作 度假村。

    DefaultFaultRule 通常是用來傳回任何 發生未預期的錯誤。例如，訊息會包含 技術支援服務這個預設回應有兩個目的 方便開發人員使用的資訊，同時模糊處理後端網址 可能用來入侵系統

多項 FaultRules 和執行邏輯

在簡易錯誤處理範例一節中，我們使用了一個簡易範例 單一 FaultRule 和條件的組合。在實際的 API 專案中，包含所有可能的錯誤 發生這種情形時，您可能需要同時擁有多個 FaultRules 和 DefaultFaultRules 《<ProxyEndpoint>》和《<TargetEndpoint>》。最終 當 API Proxy 進入錯誤狀態時，只會執行一個 FaultRule。

本節說明 Edge 處理 FaultRules 時採用的邏輯，該邏輯是從函式抵達 執行單一 FaultRule，以執行「內部」步驟條件會在其 FaultRule 時處理 本節也會說明在 <ProxyEndpoint>對<TargetEndpoint>，用於說明 FaultRules 和 PromoteFault 政策之間的關係。

FaultRules 執行

簡單來說，當 API Proxy 進入錯誤狀態時，Edge 使用的邏輯如下。請注意， 在 ProxyEndpoint 中評估 FaultRules 和 TargetEndpoint，

  1. 邊緣會依據不同因素，在 ProxyEndpoint 或 TargetEndpoint 中評估 FaultRules 發生錯誤的位置：
    • ProxyEndpoint - Edge 開頭是 bottom 設定 XML 中的 <FaultRule> 並向上運作，以評估 每個 <FaultRule> 的 <Condition> (「外部」 而不是「內部」<Step> 條件)。
    • TargetEndpoint - Edge 開頭是 top <FaultRule> 並繼續運作，目前評估 每個 <FaultRule> 的 <Condition> (「外部」 而不是「內部」<Step> 條件)。
  2. 執行條件為 true 的第一個 FaultRule。如果 FaultRule 沒有條件，預設為 true
    • 執行 FaultRule 時，系統會依序評估 FaultRule 中所有步驟， 編輯設定系統會自動執行沒有條件的步驟 (系統會執行政策) 以及具有 <Condition> 的值為「true」(判斷為「false」的條件則並非如此) 執行)。

    • 如果執行了 FaultRule，卻未執行 FaultRule 中的步驟 (因為 條件的值為「false」，則 Edge 產生的預設錯誤訊息會傳回到 用戶端應用程式。<DefaultFaultRule>「不會」執行。 因為 Edge 已執行其一個 FaultRule

  3. 如果沒有執行 FaultRule，則 Edge 會執行 <DefaultFaultRule>，如果 。

以下是內嵌註解的示例。

ProxyEndpoint 執行作業

ProxyEndpoint FaultRules 的評估由下而上，因此請開始閱讀最後讀取 請參閱下列範例的 FaultRule，並逐步進行處理。上次檢查 DefaultFaultRule，

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

目標端點執行作業

TargetEndpoint FaultRules 評估，從上到下，因此請開始閱讀 下例中的 FaultRule 並解決問題。上次檢查 DefaultFaultRule，

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

錯誤規則順序

如上一個範例所示，FultRules 的放置順序為 根據錯誤是發生在 ProxyEndpoint 和 TargetEndpoint，

例如：

ProxyEndpoint 順序 TargetEndpoint 順序

在以下範例中，由於評估作業由下至上而執行，系統會執行 FaultRule 3， 也就是不會評估 FaultRules 2 和 1。

5. FaultRule 1：FALSE

4. FaultRule 2：TRUE

3. FaultRule 3：TRUE

2. FaultRule 4：FALSE

1. FaultRule：5 FALSE

在以下範例中，由於評估作業是從上往下執行，因此系統會執行 FaultRule 2 這代表 FaultRules 3、4 和 5 不會評估。

1. FaultRule 1：FALSE

2. FaultRule 2：TRUE

3. FaultRule 3：TRUE

4. FaultRule 4：FALSE

5. FaultRule：5 FALSE

應納入的政策

您可以將 FaultRule 中的政策加進步驟，執行該政策。舉例來說： 執行 AssignMessage 政策來設定用戶端應用程式的回應格式，然後記錄訊息 建立 MessageLogging 政策。政策將按照您加入的順序執行 (XML 中由上至下)。

錯誤規則「只會」在錯誤狀態觸發 (關於 continueOnError)

標題看起來可能是我們不斷重複的標題，但還是有特定細微差異 瞭解 Proxy 錯誤導致 API Proxy 進入錯誤狀態；或者 而是不會輸入錯誤狀態：continueOnError 政策。

複習一下：API Proxy 會評估 <FaultRules> 和 <DefaultFaultRule> 只有 當 Proxy 進入錯誤狀態時。沒錯 換句話說，即使 FaultRule 條件判定為 true， 您就不會處於錯誤狀態

不過，以下的例子是發生錯誤，且 Proxy 未進入錯誤狀態。啟用 任何政策，您可以為名為 continueOnError 的父項元素設定屬性。 該屬性在處理錯誤時相當重要，因為其能 如果政策失敗，則 Proxy 會進入錯誤狀態。在大部分的情況下，建議您為 預設的 continueOnError="false"，如果系統擷取 就會觸發您的自訂錯誤處理程序。不過， continueOnError="true" (例如您不希望 Service 故障時) 呼叫停止 Proxy 執行作業的呼叫，則在下列情況中，Proxy「不會」進入錯誤狀態。 政策失敗，Proxy 不會查看您的 FaultRules。

如要瞭解 continueOnError="true" 時的記錄錯誤，請參閱「處理目前流程中的政策錯誤」。

地點 定義 FaultRules：ProxyEndpoint 或 TargetEndpoint

當 API Proxy 發生錯誤時，錯誤可能是由 <ProxyEndpoint> (從用戶端應用程式接收或回應要求)，或 <TargetEndpoint> (來自目標服務的要求或回應)。無論那件事 Edge 會尋找 FaultRules 時，就會發生這類錯誤。

舉例來說，如果目標伺服器無法使用 (HTTP 狀態碼 503)，API Proxy 會 錯誤狀態出現在 <TargetEndpoint> 回應中的錯誤狀態，以及一般 API Proxy 流量不會繼續前往 <ProxyEndpoint>如果您已定義 FaultRules 卻無法處理該錯誤。<ProxyEndpoint>

我們再看另一個例子如果 <ProxyEndpoint> 上的 PromoteFault 政策是 回應觸發錯誤，<TargetEndpoint> 中的 FaultRule 不會取得 執行狀態

FaultRules 與 PromoteFault 政策

錯誤規則和舉起 Fault 政策可能出現在表面發音，例如： 完成錯誤處理；但事實上，我認為這句話確實符合但這兩者也能搭配運作。這個 部分將說明這兩項功能之間的關係。瞭解「雙方」的關係應有助於 您需要設計錯誤處理方式，尤其是想要同時使用這兩者時。

簡單來說：

  • API Proxy 發生錯誤時，一律會評估錯誤規則 時間。

  • RaiseFault 政策是一種將 API Proxy 置於錯誤狀態的方式 就會產生錯誤

    舉例來說，假設您要擲回錯誤 目標服務的值超過 200，您會在回應中新增 PromoteFault 政策 流程網址看起來會像這樣：

    <TargetEndpoint name="default">
    <PreFlow name="PreFlow">
...
        <Response>
            <Step>
                <Name>Raise-Fault-1</Name>
<!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                <Condition>(response.status.code GreaterThan "200")</Condition>
            </Step>
        </Response>

    PromoteFault 政策也會傳送錯誤訊息至用戶端應用程式。

當 LiftFault 政策觸發錯誤，導致 Proxy 發生錯誤時，會發生什麼事 是否可能執行 FaultRule？千萬不要出去。如果 PromoteFault 政策傳回錯誤訊息「且」觸發了 FaultRule， 傳回錯誤訊息，系統會傳回什麼內容到用戶端應用程式？

  • 由於 FaultRule 或 DefaultFaultRule 是在 PromoteFault 政策中執行， FaultRule 回應資料勝出。
  • LiftFault 政策回應資料 (狀態碼、原因詞組或訊息酬載) 為 。
  • 如果 PromoteFault 政策和 FaultRule 同時新增自訂 HTTP 標頭，則兩者皆會包含在 回應。重複的標頭名稱會建立含有多個值的標頭。

以下舉例說明 LegFault 政策和 FaultRule 設定的內容和 傳回用戶端應用程式。這些範例僅供參考，而非最佳做法。

用戶端應用程式會收到：

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: woops,gremlins

<- 由錯誤規則政策設定的項目：

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: gremlins

<- PromoteFault 政策會設定此類：

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

建築物條件

條件是 FaultRule 執行作業的關鍵。建立 FaultRule 條件的方式也相同 則適用於 Edge 的其他條件，例如用於條件式流量或 PromoteFault 條件。

本節的錯誤規則範例包含外部 FaultRule 條件和內部 Step 條件。

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

政策特有的變數 錯誤數

fault.name 和 {policy_namespace}.{policy_name}.failed 變數 政策擲回錯誤時可以使用。

fault.name

如果政策失敗，請使用 fault.name 擷取條件中的錯誤 變數。例如：

<Condition>(fault.name = "policy_error_name")</Condition>

錯誤名稱會顯示在預設錯誤訊息中。例如， 名稱為 FailedToResolveAPIKey。在這個例子中，有一個稱為 fault.name 已設為 FailedToResolveAPIKey 值。

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

因此條件應如下所示：

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

請參閱政策錯誤 參考資料。

{policy_namespace}.{policy_name}.failed

政策失敗時，可以使用 *.failed 變數。追蹤對象 不同政策的 *.failed 變數範例。 如需瞭解政策命名空間，請參閱每個政策參考資料主題中的流程變數。

其他可用的變數

API Proxy 進入錯誤狀態時，唯一可在條件中使用的變數 是：

  • 失敗的政策變數。
  • 失敗時存在的 HTTP 訊息變數。舉例來說，如果錯誤是 在回應中擲回，<TargetEndpoint> 中的 FaultRule 就能使用 HTTP 資料 response.status.code，message.content， error.content 等。如果配額政策失敗，您可以使用 變數 ratelimit.{quota_policy_name}.exceed.count。使用追蹤工具和政策 參考主題，瞭解可用的變數和 HTTP 資料。

更多資訊

處理錯誤的最佳做法

錯誤處理是 API Proxy 開發的重要架構設計工作。這很重要 請花一點時間思考處理錯誤的方式和時間，判斷發生錯誤的原因 訊息，以及設計錯誤訊息格式知道這些事情之後 (或說到) 然後採用這些最佳做法，協助您實作錯誤的導入作業。

以下是設計及建構錯誤處理方式的一些最佳做法：

  • 針對每個 FaultRule，請提供「outer」<Condition> (隸屬於 <Step> 元素)。沒有外部條件的錯誤規則會自動評估 設為 true「內部」步驟條件「不會」用於判斷 FaultRule 是否為 true 或 false。只有在 Edge 執行包含這些步驟的 FaultRule 時，系統才會評估步驟條件。 在 FaultRule 中，通常會設有多個步驟來指派郵件 (或其他) 政策， 每個事件都包含步驟條件

  • 為了處理相同類型的多項政策中的錯誤 (例如多個配額) )，針對您可能收到的政策錯誤建立一個 FaultRule。例如： 為配額政策中的每個可能錯誤建立 FaultRule，例如 QuotaViolation、InvalidMessageWeight、 StartTimeNotSupported。(請參閱政策錯誤參考資料， 政策錯誤。發現其他需要處理的錯誤後， 然後將其新增至 FaultRules 中疊代也沒問題 Proxy 重新部署)。這個方法可讓您擷取同一種錯誤， 政策會被擲回，因而提高 FaultRules XML 的效率。

    如果您需要更精細的錯誤控制項，請使用內部步驟條件。例如： 假設您要同時執行兩項政策 請將要求流程設為「外部」要在 QuotaViolation 錯誤 (在任一情況下超出配額時，就會擲回此錯誤)。接著 設定步驟條件，評估兩個配額中的 exceed.count 變數 再檢查有關聯的允許政策只將相關錯誤傳送給用戶端 (開發人員配額超額或全域 配額)。設定的範例如下：

    <FaultRule name="over_quota">
<!-- This condition catches a QuotaViolation in *any* Quota policy -->
  <Condition>(fault.name = "QuotaViolation")</Condition>
  <Step>
    <Name>developer-over-quota-fault</Name>
    <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
  </Step>
  <Step>
    <Name>global-over-quota-fault</Name>
    <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
  </Step>
</FaultRule>

    如需其他範例，請參閱這個 Apigee 社群會話串。

  • 使用同一種政策時，如要處理錯誤，請考慮單一錯誤 該規則會在該政策失敗時執行，且包含對應至 的每個可能錯誤。這樣即可透過單一 FaultRule 提升 XML 效率 多個 FaultRules (每個錯誤類型各一個)。例如：

    <FaultRule name="raise-fault-3">
<!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
  <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
  <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
  <Step>
    <Name>Generic-Key-Fault</Name>
  </Step>
  <Step>
    <Name>Assign-Message-Raise-Fault-1</Name>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
  </Step>
  <Step>
    <Name>Assign-Message-Raise-Fault-2</Name>
    <Condition>(fault.name = "InvalidApiKey")</Condition>
  </Step>
</FaultRule>
    敬上
  • 新增發生錯誤的 FaultRules (用戶端 <ProxyEndpoint>) 或目標側邊 <TargetEndpoint>)。針對符合以下條件的每個政策加入 FaultRules 出現的位置。
  • 您可以在 FaultRules 中執行任何類型的政策，將訊息傳回用戶端 應用程式。AssignMessage 政策相當適合用來達成這個目標。你也可以考慮透過 MessageLogging 政策可讓您追蹤錯誤。
  • 將 PromoteFault 政策與 FaultRules 搭配使用時，會協調回應作業 flaFault 政策和 FaultRule 傳回資料時傳回的資料，適用對象 舉例來說，如果您的 PromoteFault 政策會重設 HTTP 狀態碼，則不會重設 FaultRule 狀態碼。最糟的情況是，在預設狀態碼會回傳給 用戶端應用程式。
  • <DefaultFaultRule> 執行：
    • 如果您希望 <DefaultFaultRule> 在沒有其他項目的情況下一律執行 執行 FaultRule 時，請勿在其中加入 <Condition>。
    • 如果您希望 <DefaultFaultRule> 在另一個 FaultRule 已執行，請將 <AlwaysEnforce>true</AlwaysEnforce> 子元素。

解鎖圖案 集中、可重複使用的錯誤處理

下列 Apigee 社群貼文說明的是集中化錯誤處理模式， 重複程式碼：

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

建立 FaultRules

如要新增 FaultRule，請編輯 ProxyEndpoint 的 XML 設定，或 TargetEndpoint，您可以使用 Edge UI 在下列項目的「Code」窗格中進行編輯 開發 API 檢視畫面，或編輯定義 ProxyEndpoint 或 TargetEndpoint，

如果您在管理 UI 中建立 FaultRules，請先建立要執行的政策， 然後將這些物件新增至 FaultRule 設定即可如果您嘗試儲存 參照尚未建立的政策的 FaultRule。)

將政策新增至 FaultRule

雖然您可以在 FaultRule 中放入任何政策，不過您通常會使用 AssignMessage 政策產生錯誤狀況的自訂回應訊息。 AssignMessage 可讓您設定含有酬載、HTTP 狀態碼、標頭的 HTTP 回應， 和原因詞組元素

以下範例說明典型的 AssignMessage 政策設定：

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

您現在可以在 FaultRule 中使用這項政策。請注意如何參照 AssignMessage FaultRule 中依名稱指定政策：

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

部署上方設定後，API Proxy 就會執行 AssignMessage 政策 呼叫 fault_invalidkey。

您可以在 FaultRule 中執行多項政策，如以下範例所示：

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

政策會依照指定的順序執行。舉例來說，您可以使用 MessageLogging 政策、ExtractVariables 政策、 AssignMessage 政策或 FaultRule。請注意，如果發生下列任一情況，FultRule 處理作業就會立即停止 出現：

  • FaultRule 中的任何政策都會導致錯誤
  • FaultRule 中任何政策都是 flaFault 類型

定義 從 FaultRule 呼叫的自訂錯誤訊息

最佳做法是， 相互整合進而為客戶提供一致且實用的資訊。

以下 AssignMessage 政策範例使用 <Payload>： <StatusCode> 和 <ReasonPhase> 標記來定義 發生 InvalidApiKey 錯誤時，系統傳回用戶端的錯誤回應 (請參閱先前的 FaultRules) 範例)。

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. 
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

此回應包括：

  • 酬載包含錯誤訊息，以及用於聯絡支援團隊的電子郵件地址。
  • 回應中傳回的 HTTP 狀態碼。
  • 原因詞組，是錯誤的簡短說明。

建立 DefaultFaultRule

DefaultFaultRule 對任何未由 再執行一個 FaultRule如果所有 FaultRules 的條件都不相符，則 DefaultFaultRule 會處理錯誤。啟用預設錯誤處理功能，將 <DefaultFaultRule> 標記做為 ProxyEndpoint 或 TargetEndpoint，

例如，以下的 TargetEndpoint 設定定義了叫用預設 FaultRule， 名為 ReturnGenericError 的政策：

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

DefaultFaultRule 通常用於傳回任何非預期錯誤的一般錯誤訊息 錯誤訊息，例如訊息含有技術支援聯絡資訊。預設 回應的目的在於提供適合開發人員的資訊， 模糊處理後端網址，或是可能用於入侵系統的其他資訊。

舉例來說，您可以定義下列 AssignMessage 政策傳回一般錯誤：

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

在<AlwaysEnforce> <DefaultFaultRule> 標記會針對每個錯誤執行 DefaultFaultRule 。DefaultFaultRule 一律是最後一個 FaultRule 執行：

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

DefaultFaultRule 其中一種用途是判別錯誤類型， 否則就無法判定。例如，您的 API Proxy 因發生錯誤而失敗 無法判斷。使用 DefaultFaultRule 叫用下列 AssignMessage 政策。這個 政策會將 fault.name 值寫入名為 DefaultFaultHeader 的標頭 回應：

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

您可在 Edge 追蹤工具或回應中查看標頭，瞭解導致 錯誤。

正在將訊息記錄新增至 PostClientFlow

PostClientFlow 是 Proxy 輸入錯誤後唯一執行的流程 時間。只有 MessageLogging 政策能附加至這個流程。 系統在回應 傳回至用戶端雖然將 MessageLogging 政策附加至這個流程， 技術上來說 方便您在發生錯誤的情況下記錄資訊。因為 無論 Proxy 成功還是失敗，您都可以將訊息記錄放在 政策並保證會一律執行。

處理目前流程中的政策錯誤

到目前為止，所有範例都使用 ProxyEndpoint 或 TargetEndpoint 上的 FaultRule 處理 錯誤狀態中的任何政策錯誤。這是因為 政策的 continueOnError 元素為 false，表示當 發生錯誤，控制項會導向錯誤狀態。進入錯誤狀態後 控制項無法恢復正常管道，而且您通常會傳回某種錯誤形式 傳送給呼叫應用程式的訊息。

不過，如果您將 continueOnError 元素設為 true， 政策、控制會保留在目前的流程中，並會在 。在目前流程中處理錯誤的好處是： 也許能從錯誤中復原，完成要求處理作業。

下方顯示名為 verify-api-key 的 VerifyAPIKey 政策，以及 continueOnError元素已設為 true:

<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

如果 API 金鑰遺失或無效，VerifyAPIKey 政策會設定 將 oauthV2.verify-api-key.failed 變數設為 true，但正在處理 繼續在目前的流程中繼續。

然後，在 ProxyEndpoint 的 PreFlow 中將 VerifyAPIKey 政策新增為步驟：

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>      
</ProxyEndpoint>

請注意，PreFlow 的下一步如何使用條件測試是否存在 錯誤。如果 VerifAPIKey 政策發生錯誤， 系統會執行 FaultInFlow 政策。否則，FaultInFlow 政策是 略過。FaultInFlow 政策可以執行許多作業，例如記錄錯誤。 嘗試修正錯誤或執行其他動作。

使用 PromoteFault 觸發錯誤 政策

您可以隨時在流程中使用 PromoteFault 政策來觸發錯誤。如果 crault 政策執行後會終止目前的流程，並將控管機制轉移至錯誤 時間。

flaFault 政策的用途之一是測試其他政策的特定條件 可能無法偵測出來在上述範例中，您將 <Condition> 標記新增到 導致政策「FaultInFlow」執行的 PreFlow <Step> 標記 是否相符。如果 FaultInFlow 是 PromoteFault 政策，則控制權限 傳輸到錯誤狀態或者，您可以在流程中插入 PromoteFault 政策，以便偵錯及 測試 FaultRules。

當 flaFault 政策觸發錯誤時，您可以使用下列 FaultRule 和條件 進行處理：

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

請注意，系統會對名為 RaiseFault 的錯誤進行條件測試。賴起夫 政策一律將 fault.name 的值設為 RaiseFault。

自訂 HTTP 錯誤代碼的處理方式 再從目標伺服器

前述章節中的範例適用於政策所建立的錯誤，不過， 也能針對傳輸層級錯誤建立自訂回應，意即從 複製到目標伺服器如要控管 HTTP 錯誤的回應，請將 TargetEndpoint 設定為 會處理 HTTP 回應代碼

根據預設，Edge 會將 1xx-3xx 範圍內的 HTTP 回應代碼視為「成功」，而 HTTP 回應代碼範圍介於 4xx-5xx 之間的「failure」(失敗)。這代表來自後端的任何回應 傳回 HTTP 回應代碼 4xx-5xx 的服務將自動叫用錯誤狀態， 會將錯誤訊息直接傳回給提出要求的用戶端。

您可以為任何 HTTP 回應代碼建立自訂處理常式。舉例來說 將 4xx-5xx 範圍中的所有 HTTP 回應代碼視為「失敗」但最好只傳回 5xx 傳回 HTTP 回應代碼 400 和 500 的自訂錯誤訊息。

在接下來的範例中，您將使用 success.codes 屬性設定 TargetEndpoint 將 HTTP 回應代碼 400 和 500 和預設的 HTTP 視為成功 代碼。將這些代碼視為成功後，TargetEndpoint 會接手處理 回應訊息，而不要叫用錯誤狀態：

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

如範例所示，您可以使用萬用字元，將 success.codes 屬性設為某個範圍的 值。

設定 success.codes 屬性覆寫 預設值。因此，如果您想將 HTTP 代碼 400 加入預設成功清單 程式碼，請將此屬性設為：

<Property name="success.codes">1xx,2xx,3xx,400</Property>

不過，如果您只想將 HTTP 代碼 400 視為成功代碼，請將屬性設為：

<Property name="success.codes">400</Property>

您現在可以定義用於 HTTP 回應代碼 400 和 500 的自訂處理常式，以傳回自訂的 傳送給提出要求的應用程式的回應訊息。下列 TargetEndpoint 使用的政策 ReturnError 來處理 HTTP 400 和 500 回應代碼：

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

這項 TargetEndpoint 設定會導致名為 ReturnError 的政策處理 每當 TargetEndpoint 遇到 HTTP 回應碼 400 或 500 時就會回應。

錯誤分類

API 服務將錯誤分為以下類別和子類別。

類別 子類別 錯誤名稱 說明
訊息 訊息傳送期間失敗 (不含政策失敗)
自訂錯誤 {fault_name} 由 API Proxy 使用 PromoteFault 政策明確處理的任何錯誤
回應碼 InternalServerError，找不到 HTTP 錯誤代碼 5xx、4xx
轉送失敗 NoRoutesMatched 無法為要求選取已命名的目標端點
分類失敗 NotFound 要求 URI 與任何 ProxyEndpoint 的任何 BasePath 不符，導致失敗 設定 (也就是說，沒有任何 API Proxy 與用戶端應用程式要求中的網址相符)
交通 HTTP 傳輸層級錯誤
連線能力 ConnectionRefused、ConnectionReset、ConnectionTimeout 建立網路或傳輸層級連線時發生錯誤
要求驗證 ContentLengthMissing, HostHeaderMissing 每個要求的語意檢查期間都會發生錯誤
回應驗證 每次回應的語意檢查期間都會發生錯誤
IO 錯誤 SSLHandshakeError、ReadTimeout、ReadError、WriteTimeout、WriteError、ChunkError 用戶端或目標端點的讀取/寫入錯誤、逾時、TLS/SSL 錯誤和區塊化 錯誤數
系統 未定義的執行階段錯誤
記憶體 OutOfMemory、GCOverLimit 記憶體相關故障
討論串 RogueTaskTerminated 失敗，例如終止執行作業的工作
政策 如要瞭解各種政策類型的錯誤，請參閱 政策參考資料：

錯誤一律會附加失敗原因的文字說明。當 系統會引發錯誤，填入一組屬性，協助排解問題。一項錯誤 包含下列資訊：

  • 原因
  • 使用者定義的自訂屬性