RaiseFault 政策

本页面适用于 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 将执行正常的故障处理，对 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/>
        </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>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必填
`continueOnError`	设置为 `false` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障	false	可选
`enabled`	设置为 `true` 可强制执行政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
`async`	此特性已弃用。	false	已弃用

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认值

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

不适用

如果省略此元素，则会使用政策的 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>

<AssignVariable> 元素相同的语法。

<FaultResponse><Add>/<Headers> 元素

向错误消息添加 HTTP 标头。请注意，空标头 <Add><Headers/></Add> 不会添加任何标头。此示例会将 request.user.agent 流变量的值复制到标头中。

<Header> 元素支持名为消息模板的动态字符串替换功能。

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

默认：	不适用
状态：	可选
类型：	字符串

<FaultResponse><Copy> 元素

将信息从 source 属性指定的消息复制到错误消息。

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

默认：	不适用
状态：	可选
类型：	字符串

特性

 <Copy source="response">

属性	说明	状态	类型
来源	指定副本的来源对象。如果未指定来源，则系统会将其视为简单消息。例如，如果政策位于请求流中，则来源默认为请求对象。如果该政策位于响应流中，则默认为响应对象。如果省略来源，则可以使用对流变量的绝对引用作为副本的来源。例如，将值指定为 {request.header.user-agent}。如果源变量无法解析或解析为非消息类型，则 <Copy> 会无响应。	可选	字符串

属性

说明

状态

类型

来源

指定副本的来源对象。

如果未指定来源，则系统会将其视为简单消息。例如，如果政策位于请求流中，则来源默认为请求对象。如果该政策位于响应流中，则默认为响应对象。如果省略来源，则可以使用对流变量的绝对引用作为副本的来源。例如，将值指定为 {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> 的子元素支持名为消息模板化的动态字符串替换功能。

    <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 政策后，可以获得以下预定义的流变量。如需详细了解流变量，请参阅变量参考。

变量	类型	权限	说明
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 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码	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`

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

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

架构

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

RaiseFault 政策

内容

示例

返回 FaultResponse

返回 FaultResponse 载荷

处理服务调出错误

关于 RaiseFault 政策

元素参考

<RaiseFault> 属性

<DisplayName> 元素

<IgnoreUnresolvedVariables> 元素

<FaultResponse> 元素

<FaultResponse><AssignVariable> 元素

<FaultResponse><Add>/<Headers> 元素

<FaultResponse><Copy> 元素

特性

<FaultResponse><Copy>/<Headers> 元素

<FaultResponse><Copy>/<StatusCode> 元素

<FaultResponse><Remove>/<Headers> 元素

<FaultResponse><Set> 元素

<FaultResponse>/<Set>/<Headers> 元素

<FaultResponse>/<Set>/<Payload> 元素

特性

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

<ShortFaultReason> 元素

流变量

RaiseFault 的示例用法

错误参考信息

运行时错误

部署错误

故障变量

错误响应示例

架构

相关主题