isingFault 政策

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

結果

產生自訂訊息以回應錯誤狀況。使用 flaFault 來定義 發生特定條件時，傳回的錯誤回應。

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

範例

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

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

關於 flaFault 政策

Apigee Edge 可讓您使用 PromoteFault 類型的政策執行自訂例外狀況處理。 flaFault 政策，與 AssignMessage 政策 可讓您產生自訂錯誤回應來回應錯誤狀況。

使用 PromoteFault 政策定義了傳回要求應用程式的錯誤回應 發生特定錯誤狀況時錯誤回應可包含 HTTP 標頭、查詢 參數和訊息酬載自訂錯誤回應對應用程式開發人員來說可能更實用 而非一般的錯誤訊息或 HTTP 回應代碼

執行時，PromoteFault 政策的控管機制會從目前流程轉移至 Error 資料流，然後將指定的錯誤回應傳回給提出要求的用戶端應用程式。當 「Flow」訊息會切換至「錯誤」流程，不會進一步處理政策。全部剩餘 系統就會略過處理程序，並且直接將錯誤回應傳回至 應用程式。

您可以在 ProxyEndpoint 或 TargetEndpoint 中使用 PromoteFault。您通常會提供 「Condition」為 flaFault 政策。flaFault 執行後，Apigee 會正常執行 錯誤處理， 如未定義錯誤規則，就會終止處理程序 。

元素參照

元素參照會說明 PromoteFault 政策的元素和屬性。

<?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">

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

<DisplayName>元素

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

<DisplayName>Policy Display Name</DisplayName>

<IgnoreUnresolvedVariables>元素

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

<FaultResponse>元素

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

<FaultResponse><AssignVariable>元素

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

舉例來說，請使用以下程式碼設定名為 myFaultVar 的變數 向 PromoteFault 政策要求成員：

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

您之後可以在訊息範本的 PromoteFault 政策中參照該變數。 此外，附加至 FaultRule 的政策就能存取變數。例如，下列 AssignMessage 政策會使用 PromoteFault 中設定的變數，以設定標頭中的 錯誤回應：

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

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

<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/>
        <ReasonPhrase/>
    </Copy>

屬性

 <Copy source="response">

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

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

要從來源屬性指定物件複製到錯誤的原因說明 撰寫新的電子郵件訊息

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

<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/>
        <ReasonPhrase/>
    </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">

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

設定回應的狀態碼。

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

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

設定回應的原因語句。

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

<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(預設值)。

流程變數

流程變數會根據 HTTP 在執行階段啟用政策和流程的動態行為 標頭、郵件內容或流程背景資訊可用的預先定義 Flow 變數如下 一定會發生。如要進一步瞭解流程變數，請參閱變數參考資料。

flaFault 使用範例

以下範例使用 Condition (條件) 強制規定 傳入要求中名為 zipcode 的 queryparam。如果 queryparam 不存在時，資料流會透過 flaFault 引發錯誤：

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

錯誤參考資料

本節說明系統傳回的錯誤代碼和錯誤訊息，以及錯誤變數。 這項政策觸發錯誤時，由 Edge 設定的。 請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則， 處理錯誤詳情請參閱： 政策錯誤須知和 處理錯誤。

執行階段錯誤

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

部署錯誤

無。

錯誤變數

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

錯誤回應範例

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

結構定義

每種政策類型都是由 XML 架構 (.xsd) 定義。供參考政策結構定義 GitHub 提供許多資源。

相關主題

請參閱處理錯誤