有关政策错误的注意事项

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本主题介绍政策错误的结构以及发生政策错误时设置的流变量种类。如果您要为代理设计和实现故障处理，此信息非常重要。

本主题假设您大致了解错误处理在 Apigee 中的工作原理，并了解什么是错误规则。如果您需要进行回顾，请参阅处理故障。此处的信息还可帮助您浏览和使用政策错误参考文档。

默认政策错误响应简介

当政策抛出错误时，Apigee 会立即进入错误流并生成错误消息。该系统生成的消息是一个 JSON 对象，它包含 errorcode 和 faultstring 这两种信息。

注意：了解如下所示的错误中的部分可用作流变量，这一点非常有用。您可以通过这些变量重新构建和自定义错误消息。变量 fault.name 是 errorcode 特性的值，error.message 是 faultstring 特性的值。本主题的以下部分将详细介绍这些变量。

例如：

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"mymessage message is not available for ExtractVariable: ParseJsonResponse"
   }
}

让我们快速解构此错误消息：

errorcode 由 prefix 和 error name 组成，如下所示：[prefix].[error_name]。在上面的示例中，steps.extractvariables 是前缀，SourceMessageNotAvailable 是错误名称。前缀可让您了解生成错误的政策的种类。在上面的示例中，您可以看到 ExtractVariables 政策生成了错误，错误名称为 SourceMessageNotAvailable。

faultstring 包含错误描述。故障字符串通常包含线索，可帮助您找到导致错误的具体问题，例如政策名称、未解析变量的名称或导致错误的任何原因。例如，在上述错误消息中，mymessage 是政策中引用的未解析消息变量的名称，ParseJsonResponse 是触发错误的政策的名称。

注意：在政策错误参考文档中，我们使用一致的惯例来记录政策错误字符串。我们使用 [] 表示法指示放置变量的位置。以下示例展示了如何记录上述错误的故障字符串：

VAR_NAME message is not available for ExtractVariable: POLICY_NAME

政策错误特有的变量

当触发政策错误时，某些特定于错误的流变量将被填充。这些变量在故障处理中非常有用。如处理故障主题中所述，捕获系统生成的政策错误并执行后续操作（例如创建自定义错误响应）是一种常见的做法。例如，出于安全原因，您可能需要禁止客户端查看 Apigee 返回的实际错误和状态代码。

fault.name 变量

当政策抛出错误时，它会将流变量 fault.name 设置为 errorcode 的 error_name 部分（如上一部分中所述）。在有条件执行故障规则时，通常要评估此变量。

下面是一个示例故障规则，用于测试 fault.name 的值：

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Source Message Not Available Fault">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
    </Step>
</FaultRule>

请记住，当政策触发错误时，fault.name 变量始终设置为错误名称。

注意：在开发故障处理代码时，只需查看政策错误参考文档，以了解每种政策错误的错误名称。使用 Debug 工具检查错误响应和设置的变量也是一种常见的做法。

[prefix].[policy_name].failed 变量

除 fault.name 外，开发者通常检查的另一个变量是 [prefix].[policy_name].failed 标志，该标志会在执行政策时设为 true 或 false。在故障规则中，您需要检查其何时为 true，也就是检查是否出现了错误。以下代码显示如何构建条件来检查 [prefix].[policy_name].failed 标志。如需正确检查此变量，您需要了解以下两点：

• 您正在检查的政策的名称。这是政策的名称特性的值，而不是显示名。该特性始终包含在政策定义的 XML 中。
• 特定于您正在检查的政策类型的前缀。（我们将在下文中说明如何查找前缀。）

为便于说明，我们来看另一个故障规则示例。请注意在外部条件中 [prefix].[policy_name].failed 变量名称是如何形成的。在本例中，前缀为 extractvariables，政策名称为 ParseJsonResponse。在这种情况下，只有在此变量为 true 时，故障规则才会执行。这有一个诀窍，由于错误规则可能包含多个步骤，因此这种模式非常适合将错误规则整理成块。

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.ParseJsonResponse.failed = true) </Condition>
</FaultRule>

注意：如何知道故障变量的前缀是什么？您不一定能从故障字符串或错误代码的内容中猜出来。必须在政策错误参考文档中查找，或使用跟踪记录来检查发生错误时创建的流变量。例如，对于提取变量政策而言，[prefix].[policy_name].failed 前缀为 extractvariables，这非常简单。但对于访问权限控制政策而言，前缀为 acl。因此，重点是您必须进行检查。

error 和 message 变量简介

error 变量仅在代理的错误流中可用。您可以从 error 变量中获取有用的信息，例如错误消息、状态代码等。错误变量的格式模式如下：

error.ERROR_COMPONENT = VALUE

例如：

error.message = "request message is not available for ExtractVariable:
  ParseJsonResponse"

和

error.status.code = "500"

提示：您还可以使用此变量设置响应标头。这非常有用，因为在错误流中，响应对象不可用。

message 变量在错误流中也可用，并且可以用于与 error 变量类似的用途。消息变量比较特殊，因为它是上下文相关的。在请求流中，它的行为类似于请求变量，而在响应流程中它可用于获取/设置响应值。

如需了解所有 Apigee 变量（包括 error 和 message），请参阅流变量参考。