isingFault 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

產生自訂訊息，以回應錯誤狀況。當發生特定情況時，請使用 RaiseFault 定義要傳回給要求應用程式的錯誤回應。

這項政策屬於標準政策，可部署至任何環境類型。如要瞭解各環境類型適用的政策類型和可用性，請參閱「政策類型」。

如需處理錯誤的一般資訊，請參閱「處理錯誤」。

範例

傳回 FaultResponse

在最常見的用法中，RaiseFault 會用於將自訂錯誤回應傳回給提出要求的應用程式。舉例來說，這項政策會傳回 404 狀態碼，且沒有酬載：

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

傳回 FaultResponse 酬載

更複雜的範例是傳回自訂錯誤回應酬載，以及 HTTP 標頭和 HTTP 狀態碼。在下列範例中，錯誤回應會填入 XML 訊息，其中包含 Apigee 從後端服務收到的 HTTP 狀態碼，以及包含發生錯誤類型的標頭：

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact [e-mail]</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

如需可用於動態填入 FaultResponse 訊息的所有變數清單，請參閱變數參考資料

處理服務回呼錯誤

範例： 邊做邊學！
這個 瞭解 Apigee 範例會說明如何檢查 ServiceCallout 回應中的 HTTP 程式碼，並根據程式碼的值擲回自訂例外狀況。如果目標服務傳回 404 狀態，這個範例會傳回自訂錯誤訊息。只要複製存放區，然後按照該主題中的指示操作即可。這個範例說明處理服務呼叫錯誤的常見模式。

---

關於 RaiseFault 政策

Apigee 可讓您使用 RaiseFault 類型的政策執行自訂例外狀況處理作業。RaiseFault 政策與 AssignMessage 政策類似，可讓您在發生錯誤時產生自訂錯誤回應。

當發生特定錯誤情況時，請使用 RaiseFault 政策定義要傳回給要求應用程式的錯誤回應。錯誤回應可包含 HTTP 標頭、查詢參數和訊息酬載。相較於一般錯誤訊息或 HTTP 回應碼，自訂錯誤回應對應用程式開發人員和應用程式使用者來說更有用。

執行時，RaiseFault 政策會將控制權從目前流程轉移至錯誤流程，然後將指定的錯誤回應傳回給要求用戶端應用程式。訊息流程切換至錯誤流程後，系統不會再處理任何政策。系統會略過所有剩餘的處理步驟，並直接將錯誤回應傳回給要求應用程式。

您可以在 ProxyEndpoint 或 TargetEndpoint 中使用 RaiseFault。通常您會將 Condition 附加至 RaiseFault 政策。執行 RaiseFault 後，Apigee 會執行正常的錯誤處理、評估 FaultRules，如果沒有定義錯誤規則，則會終止處理要求。

元素參考資料

元素參考資料說明 RaiseFault 政策的元素和屬性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

<RaiseFault> 屬性

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

下表說明所有政策父項元素的共同屬性：

屬性	說明	預設	存在必要性
name	政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
continueOnError	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。 將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
enabled	設為 true 即可強制執行政策。 設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
async	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設	不適用 如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性	選用
類型	字串

<IgnoreUnresolvedVariables> 元素

(選用) 忽略 Flow 中任何未解決的變數錯誤。有效值：true/false。 預設值為 true。

<FaultResponse> 元素

(選用) 定義傳回給要求用戶端的回應訊息。FaultResponse 使用的設定與 AssignMessage 政策相同。

<FaultResponse><AssignVariable> 元素

將值指派給目的地流程變數。 如果流程變數不存在，AssignVariable 會建立該變數。

舉例來說，使用下列程式碼在 RaiseFault 政策中設定名為 myFaultVar 的變數：

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

然後，您可以在 RaiseFault 政策中稍後參照該變數。 此外，附加至 FaultRule 的政策隨後也能存取變數。舉例來說，下列 AssignMessage 政策會使用 RaiseFault 中設定的變數，在錯誤回應中設定標頭：

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

RaiseFault 政策中的 <AssignVariable> 使用的語法，與 AssignMessage 政策中的 <AssignVariable> 元素相同。

<FaultResponse><Add>/<Headers> 元素

在錯誤訊息中加入 HTTP 標頭。請注意，空白標頭 <Add><Headers/></Add> 不會新增任何標頭。這個範例會將 request.user.agent 流程變數的值複製到標頭中。

<Header> 元素支援名為「訊息範本」的動態字串替代功能。

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

預設值：	不適用
外觀狀態：	選用
類型：	字串

<FaultResponse><Copy> element

將 source 屬性指定的訊息複製到錯誤訊息。

    <Copy source="request">
        <Headers/>
        <StatusCode/>
    </Copy>

預設值：	不適用
外觀狀態：	選用
類型：	字串

屬性

 <Copy source="response">

屬性	說明	存在必要性	類型
來源	指定副本的來源物件。 如未指定 source，系統會將其視為簡單訊息。舉例來說，如果政策位於要求流程中，來源預設為要求物件。如果政策位於回應流程中，預設會是 response 物件。如果省略 source，則可以使用流程變數的絕對參照做為副本來源。舉例來說，您可以將值指定為 {request.header.user-agent}。 如果無法解析來源變數，或解析為非訊息類型，<Copy> 就無法回應。	選用	字串

<FaultResponse><Copy>/<Headers> 元素

將來源中的指定 HTTP 標頭複製到錯誤訊息。如要複製所有標頭，請指定 <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>
        <Header name="headerName"/>
    </Headers>
</Copy>

如果有多個同名標頭，請使用下列語法：

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

這個範例會複製「h1」、「h2」和「h3」的第二個值。如果「h3」只有一個值，系統就不會複製。

預設值：	不適用
外觀狀態：	選用
類型：	字串

<FaultResponse><Copy>/<StatusCode> 元素

要從來源屬性指定的物件複製到錯誤訊息的 HTTP 狀態碼。

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

預設值：	false
外觀狀態：	選用
類型：	字串

<FaultResponse><Remove>/<Headers> 元素

從錯誤訊息中移除指定的 HTTP 標頭。如要移除所有標頭，請指定 <Remove><Headers/></Remove>。這個範例會從郵件中移除 user-agent 標頭。

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

如果有多個同名標頭，請使用下列語法：

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

這個範例會移除「h1」、「h2」和「h3」的第二個值。如果「h3」只有一個值，就不會移除。

預設值：	不適用
外觀狀態：	選用
類型：	字串

<FaultResponse><Set> 元素

設定錯誤訊息中的資訊。

<Set> 的子元素支援稱為「訊息範本」的動態字串替代功能。

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
    </Set>

預設值：	不適用
外觀狀態：	選用
類型：	不適用

<FaultResponse>/<Set>/<Headers> 元素

設定或覆寫錯誤訊息中的 HTTP 標頭。請注意，空白標頭 <Set><Headers/></Set> 不會設定任何標頭。本例會將 user-agent 標頭設為以 <AssignTo> 元素指定的訊息變數。

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

預設值：	不適用
外觀狀態：	選用
類型：	字串

<FaultResponse>、<Set> 或 <Payload> 元素

設定錯誤訊息的酬載。

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

設定 JSON 酬載：

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

在 JSON 酬載中，您可以使用 variablePrefix 和 variableSuffix 屬性插入變數，並以分隔符號字元分隔，如下列範例所示。

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

或者，自 16.08.17 版雲端發布起，您也可以使用大括號插入變數：

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

在 XML 中設定混合式酬載：

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

預設值：
外觀狀態：	選用
類型：	字串

屬性

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

屬性	說明	存在必要性	類型
contentType	如果指定了 contentType，系統會將其值指派給 Content-Type 標頭。	選用	字串
variablePrefix	選擇性指定流程變數的前置分隔符，因為 JSON 酬載無法使用預設的「{」字元。	選用	Char
variableSuffix	選擇性指定流程變數的尾端分隔符，因為 JSON 酬載無法使用預設的「}」字元。	選用	Char

<FaultResponse>/<Set>/<StatusCode> 元素

設定回應的狀態碼。

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

預設值：	false
外觀狀態：	選用
類型：	布林值

<ShortFaultReason> 元素

指定在回應中顯示簡短的錯誤原因：

<ShortFaultReason>true|false</ShortFaultReason>

根據預設，政策回應中的錯誤原因如下：

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

如要讓訊息更容易閱讀，您可以將 <ShortFaultReason> 元素設為 true，將 faultstring 縮短為只有政策名稱：

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

有效值：true/false(預設值)。

預設值：	false
外觀狀態：	選用
類型：	布林值

流程變數

流程變數可讓政策和流程在執行階段根據 HTTP 標頭、訊息內容或流程環境，動態調整行為。執行 RaiseFault 政策後，即可使用下列預先定義的 Flow 變數。如要進一步瞭解流程變數，請參閱「變數參考資料」。

變數	類型	權限	說明
fault.name	字串	唯讀	執行 RaiseFault 政策時，這個變數一律會設為字串「RaiseFault」。
fault.type	字串	唯讀	傳回錯誤中的錯誤類型，如果沒有，則傳回空字串。
fault.category	字串	唯讀	傳回錯誤中的錯誤類別，如果沒有，則傳回空字串。

RaiseFault 的使用範例

以下範例使用 Condition，強制要求傳入要求中必須有名稱為 zipcode 的 queryparam。如果沒有 queryparam，流程會透過 RaiseFault 引發錯誤：

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>

下圖說明 RaiseFault 的內容：

<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
    </Set>
  </FaultResponse>
</RaiseFault>

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「 政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼	HTTP 狀態	原因
steps.raisefault.RaiseFault	500	請參閱錯誤字串。

部署錯誤

無

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱 政策錯誤須知事項。

變數	地點	範例
fault.name="fault_name"	fault_name 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一部分。	fault.name = "RaiseFault"
raisefault.policy_name.failed	policy_name 是擲回錯誤的政策的使用者指定名稱。	raisefault.RF-ThrowError.failed = true

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

結構定義

每個政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。

相關主題

請參閱「處理錯誤」