isingFault 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

產生回應錯誤狀況的自訂訊息。使用 riseFault 定義錯誤回應,以便在特定條件發生時,將錯誤回應傳回給提出要求的應用程式。

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

範例

傳回錯誤回應

在最常使用的使用情形中,提出 GrowFault 後,會將自訂錯誤回應傳回給要求權限的應用程式。舉例來說,這項政策會傳回不含酬載的 404 狀態碼:

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

傳回錯誤回應酬載

較複雜的範例包括傳回自訂錯誤回應酬載、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 訊息的所有變數清單,請參閱變數參考資料

處理服務呼叫錯誤


關於 GrowFault 政策

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

使用 riseFault 政策來定義錯誤回應,以便在發生特定錯誤狀況時,傳回給提出要求的應用程式。錯誤回應可包含 HTTP 標頭、查詢參數和訊息酬載。相較於一般錯誤訊息或 HTTP 回應代碼,自訂錯誤回應對應用程式開發人員和應用程式使用者而言更為實用。

執行時,riseFault 政策將控制項從目前的流程轉移至錯誤流程,然後再將指定的錯誤回應傳回給提出要求的用戶端應用程式。當訊息流程切換至「錯誤」流程時,系統就不會繼續處理政策。系統會略過其餘的處理步驟,並將錯誤回應直接傳回給提出要求的應用程式。

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

元素參照

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

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

<ObservFault> 屬性

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

下表說明所有政策父項元素的通用屬性:

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

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

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

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

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

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

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<IgnoreUnresolvedVariables> 元素

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

<FaultResponse> 元素

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

<FaultResponse><AssignVariable> 元素

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

舉例來說,請使用下列程式碼設定 riseFault 政策中名為 myFaultVar 的變數:

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

接著,您就可以透過 upsFault 政策在訊息範本中參照該變數。此外,附加於 FaultRule 的政策就可以存取變數。例如,下列 AssignMessage 政策會使用 riseFault 中設定的變數設定錯誤回應中的標頭:

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

riseFault 政策中的 <AssignVariable> 使用的語法與 AssignMessage 政策中的 <AssignVariable> 元素相同。請注意,適用於私有雲的 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">
屬性 說明 存在必要性 類型
來源

指定副本的來源物件。

  • 如未指定 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><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」只有一個值,就不會移除。

預設:

不適用

所在地:

選用

類型:

字串

<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 酬載中,您可以使用具有分隔符號字元的 variablePrefixvariableSuffix 屬性插入變數,如以下範例所示。

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

或自 Cloud 版本 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 酬載無法使用預設的「{」字元。 選用 圖表
variableSuffix 您可以選擇指定流程變數的結尾分隔符號,因為 JSON 酬載無法使用預設的「"}」字元。 選用 圖表

<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 標頭、訊息內容或流程結構定義,在執行階段啟用政策和流程的動態行為。執行 riseFault 政策後,即可使用下列預先定義的流程變數。如要進一步瞭解流程變數,請參閱變數參考資料

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

ImprFault 的使用範例

以下範例使用「條件」在傳入要求中強制出現名稱為 zipcodequeryparam。如未出現該 queryparam,資料流將透過 李 Fault 發出錯誤:

<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>
以下是 riseFault 的內容:
<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 設定的錯誤變數。如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱 政策錯誤須知處理錯誤

執行階段錯誤

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

錯誤代碼 HTTP 狀態 原因
steps.raisefault.RaiseFault 500 查看錯誤字串。

部署錯誤

無。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
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 提供政策結構定義

相關主題

請參閱處理錯誤