您正在查看 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 |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<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">
屬性 | 說明 | 存在必要性 | 類型 |
---|---|---|---|
來源 |
指定副本的來源物件。
|
選用 | 字串 |
<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 酬載中,您可以使用具有分隔符號字元的 variablePrefix
和 variableSuffix
屬性插入變數,如以下範例所示。
<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,系統會將其值指派給 |
選用 | 字串 |
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 的使用範例
以下範例使用「條件」在傳入要求中強制出現名稱為 zipcode
的 queryparam
。如未出現該 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 提供政策結構定義。
相關主題
請參閱處理錯誤