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 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 政策

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

使用 RaiseFault 政策定義錯誤回應，在發生特定錯誤情況時傳回給要求應用程式。錯誤回應可包含 HTTP 標頭、查詢參數和訊息酬載。自訂錯誤回應比一般錯誤訊息或 HTTP 回應碼更實用，可提供給應用程式開發人員和應用程式使用者。

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

您可以在 ProxyEndpoint 或 TargetEndpoint 中使用 RaiseFault。通常您會將條件附加至 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，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

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

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

不適用

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

<IgnoreUnresolvedVariables> 元素

(選用) 忽略流程中未解決的變數錯誤。有效值：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 流程變數的值複製到標頭中。

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

預設值：

 不適用

外觀狀態：

 選用

類型：

 字串

<FaultResponse><Copy> 元素

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

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

預設值：

不適用

外觀狀態：

選用

類型：

字串

屬性

 <Copy source="response">
屬性 說明 存在必要性 類型
來源

指定複本的來源物件。

  • 如果未指定 source，系統會將其視為簡單訊息。舉例來說，如果政策位於要求流程中，來源就會預設為 request 物件。如果政策位於回應流程中，則預設為 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>
        <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 變數。如要進一步瞭解 Flow 變數，請參閱「變數參考資料」。

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

RaiseFault 使用範例

以下範例使用條件，在傳入要求中強制設有名稱為 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

錯誤回應範例

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

結構定義

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

相關主題

請參閱「處理錯誤」