RaiseFault 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

内容

生成自定义消息来响应错误情况。使用 RaiseFault 可以定义发生特定情况时向发出请求的应用返回的故障响应。

如需了解有关处理故障的一般信息，请参阅处理故障。

示例

返回 FaultResponse

在最常见的用法中，RaiseFault 用于将自定义故障响应返回给 发出请求。例如，此政策将返回 404 状态代码， 无载荷：

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

返回 FaultResponse 载荷

较复杂的示例涉及到返回自定义故障响应载荷以及 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 消息的所有变量的列表，请参阅变量参考

处理服务调出错误

关于 RaiseFault 政策

借助 Apigee Edge，您可以使用 RaiseFault 类型的政策执行自定义异常处理。 ManagedFault 政策，类似于 AssignMessage 政策 可以生成自定义故障响应，以响应错误情况。

使用 RaiseFault 政策可以定义发生特定错误情况时向发出请求的应用返回的故障响应。故障响应可以包含 HTTP 标头、查询参数和消息载荷。对应用开发者和最终用户来说，自定义故障响应比一般错误消息或 HTTP 响应代码更为有用。

执行时，RaiseFault 政策会将控制权从当前流转移到错误流，然后后者向发出请求的客户端应用返回指定的故障响应。当消息流切换为错误流时，不会进行进一步的政策处理。系统会忽略所有剩余的处理步骤，并将故障响应直接返回给发出请求的应用。

您可以在 ProxyEndpoint 或 TargetEndpoint 中使用 RaiseFault。通常情况下，您需要将条件附加到 RaiseFault 政策。RaiseFault 执行后，Apigee 将执行正常的故障处理，对 FaultRule 进行评估；如果未定义故障规则，则会终止请求的处理。

元素参考

元素参考介绍 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/>
            <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">

下表介绍了所有政策父元素通用的特性：

属性 说明 默认 状态
name

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

（可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必填
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true，即使在政策失败后，仍可以继续执行流。

 false 可选
enabled

设置为 true 可强制执行政策。

设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。

 是 可选
async

此特性已弃用。

 false 已弃用

<DisplayName> 元素

除了用于 name 属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素，则会使用政策的 name 属性的值。
状态 可选
类型 字符串

<IgnoreUnresolvedVariables> 元素

（可选）忽略流中任何未解决的变量错误。有效值：true/false。默认为 true。

<FaultResponse> 元素

（可选）定义返回到发出请求的客户端的响应消息。FaultResponse 使用 与 AssignMessage 政策相同的设置（在适用于私有云的 Apigee Edge 中不可用）。

<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>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

RaiseFault 政策中的 <AssignVariable> 使用的语法与 AssignMessage 政策中的 <AssignVariable> 元素。请注意，此功能 Apigee Edge 目前尚未在适用于私有云的 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">
属性 说明 状态 类型
来源

指定副本的来源对象。

  • 如果未指定来源，则系统会将其视为简单消息。例如，如果政策位于请求流中，则来源默认为请求对象。如果该政策位于响应流中，则默认为响应对象。如果省略来源，则可以使用对流变量的绝对引用作为副本的来源。例如，将值指定为 {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 载荷中，您可以使用带分隔符的 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

状态：

 可选

类型：

 布尔值

<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 标头、消息内容或流上下文支持政策和流的动态行为。执行 RaiseFault 政策后，可以获得以下预定义的流变量。如需详细了解流变量，请参阅变量参考。

变量 类型 权限 说明
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>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

错误参考信息

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

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

架构

每种政策类型均由 XML 架构 (.xsd) 定义。GitHub 提供了政策架构作为参考。

相关主题

请参阅处理故障