isingFault 政策

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

查看 Apigee Edge 說明文件。

RaiseFault 政策會產生自訂訊息，以回應錯誤情況。當發生特定情況時，請使用 RaiseFault 定義要傳回給要求應用程式的錯誤回應。相較於一般錯誤訊息或 HTTP 回應碼，自訂錯誤回應對應用程式開發人員和應用程式使用者來說更有用。

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

自訂錯誤回應可包含 HTTP 標頭、查詢參數和訊息酬載。您可以在 ProxyEndpoint 或 TargetEndpoint 中使用 RaiseFault。通常您會將 Condition 附加至 RaiseFault 政策。執行 RaiseFault 後，Apigee 會執行正常的錯誤處理、評估錯誤規則，或在未定義錯誤規則的情況下，終止處理要求。

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

視用途而定，您可能會想使用 RaiseFault 政策或 AssignMessage 政策。

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

範例

傳回 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 support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

如要查看可動態填入 FaultResponse 訊息的所有變數清單，請參閱變數參考資料。

處理服務呼叫錯誤

元素參考資料

元素參考資料說明 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` 屬性值。
存在必要性	選用
類型	字串

不適用

如果省略這個元素，系統會使用政策的 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> 就無法回應。	選用	字串

屬性

說明

狀態

類型

來源

指定副本的來源物件。

如未指定 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 政策後，即可使用下列預先定義的流程變數。如要進一步瞭解流程變數，請參閱「變數參考資料」。

變數	類型	權限	說明
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>

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

結構定義

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

isingFault 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

範例

傳回 FaultResponse

傳回 FaultResponse 酬載

處理服務呼叫錯誤

元素參考資料

<RaiseFault> 屬性

<DisplayName> 元素

<IgnoreUnresolvedVariables> 元素

<FaultResponse> 元素

<FaultResponse><AssignVariable> 元素

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

<FaultResponse><Copy> element

屬性

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

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

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

<FaultResponse><Set> 元素

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

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

屬性

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

<ShortFaultReason> 元素

流程變數

RaiseFault 的使用範例

錯誤參考資料

Runtime errors

Deployment errors

Fault variables

Example error response

結構定義

相關主題

isingFault 政策