isingFault 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

針對錯誤情況生成自訂訊息。您可以使用 RaiseFault 定義錯誤回應，在發生特定情況時傳回給提出要求的應用程式。

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

範例

傳回 FaultResponse

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

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

傳回 FaultResponse 酬載

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

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

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

處理服務呼叫錯誤

關於 RaiseFault 政策

您可以使用 RaiseFault 類型的政策，在 Apigee Edge 中執行自訂例外狀況處理作業。 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/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

<RaiseFault> 屬性

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

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

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以 包含英文字母、數字、空格、連字號、底線和半形句號。此值不能 超過 255 個半形字元

視需要使用 <DisplayName> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

如要強制執行政策，請設為 true。

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性 選用
類型 字串

<IgnoreUnresolvedVariables> 元素

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

<FaultResponse> 元素

(選用) 定義傳回給提出要求用戶端的回應訊息。FaultResponse 使用與指派訊息政策相同的設定 (不適用於 Apigee Edge for Private Cloud)。

<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>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

RaiseFault 政策中的 <AssignVariable> 使用的語法，與 AssignMessage 政策中的 <AssignVariable> 元素相同。請注意，這項功能目前不適用於 Apigee Edge Private Cloud。

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

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

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

預設值：

 N/A

外觀狀態：

 選用

類型：

 字串

<FaultResponse><Copy> element

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

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

預設值：

N/A

外觀狀態：

選用

類型：

字串

屬性

 <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」只有一個值，就不會複製。

預設值：

N/A

外觀狀態：

 選用

類型：

字串

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

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

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

預設值：

 false

外觀狀態：

 選用

類型：

 字串

<FaultResponse><Copy>/<ReasonPhrase> 元素

要從來源屬性指定的物件複製到錯誤訊息的原因說明。

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</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」只有一個值，就不會移除。

預設值：

 N/A

外觀狀態：

 選用

類型：

 字串

<FaultResponse><Set> 元素

設定錯誤訊息中的資訊。

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

預設值：

 N/A

外觀狀態：

 選用

類型：

 N/A

<FaultResponse>、<Set>、<Headers> 元素

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

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

預設值：

 N/A

外觀狀態：

 選用

類型：

 字串

<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

外觀狀態：

 選用

類型：

 布林值

<FaultResponse>/<Set>/<ReasonPhrase> 元素

設定回應的原因片語。

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</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 政策後，即可使用下列預先定義的流程變數。如要進一步瞭解流程變數，請參閱「變數參考資料」。

變數 類型 權限 說明
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>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.raisefault.RaiseFault 500 See fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RaiseFault"
raisefault.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. raisefault.RF-ThrowError.failed = true

Example error response

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

結構定義

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

相關主題

請參閱「處理錯誤」