此页面由 Cloud Translation API 翻译。

调试扩展程序

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

您可以通过在两个位置（Trace 工具和扩展程序日志）查看消息来调试扩展程序。如果扩展程序无法正常运行，有时可能需要从这两个位置获取信息来确定问题。

您可以使用 Apigee Edge 的 Trace 工具在开发 API 代理代码时迭代测试和修改代码。轨迹消息包含 API 代理代码中的错误，包括 API 代理和政策配置。

跟踪工具中显示的与扩展程序相关的错误通常不会包含太多详细信息，只会说明哪个扩展程序宣传信息失败，以及 HTTP 错误代码。如果您在这里没有看到任何有用的信息，下一个最合适的查看位置是您所用扩展程序的日志。
扩展程序会在运行时生成日志条目。（扩展程序日志仅供组织管理员使用。）

这些日志包含扩展程序配置为与之交互的外部资源返回的条目。例如，如果扩展程序中外部资源凭据配置有误，则错误可能会显示在此处。

日志还包含来自内部扩展程序代码的条目。查看日志时，请注意其中有些条目与您要更正的错误无关。与扩展程序相关的日志条目通常以 details 开头，如 Cloud Pub/Sub 扩展程序中的以下日志条目所示：
```
details: 'Invalid resource name given (name=projects/example-test-123456/topic/extension-example). Refer to https://cloud.google.com/pubsub/docs/admin#resource_names for more information.'
```

错误类型和原因

扩展程序请求处理流程从 API 代理中的 ExtensionCallout 政策开始，通过扩展程序到达外部资源，然后返回。因此，这些任一位置都可能会发生错误。

您看到的错误可能属于以下类别。

扩展程序配置中存在错误

这是组织管理员在向环境添加扩展程序时进行的配置。

例如，如果您使用不正确的 Google Cloud 项目 ID 配置 Cloud Logging 扩展程序，Google Cloud Logging 会向该扩展程序返回错误。有关这些错误的详细信息通常位于扩展程序日志中。

Trace 工具中的证据

在代理编辑器中，这些错误通常会显示为 4xx 级或 5xx 级错误。不过，代理编辑器不会显示有关错误原因的任何具体信息，只会说明扩展程序返回了错误。

{
  "fault": {
    "faultstring":"Execution of ConnectorCallout Logging-Extension failed. Reason: Connector returned error statuscode=500",
    "detail": {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

扩展程序日志中的证据

如果有关于此类错误的详细信息，您会在扩展程序的日志条目中看到。Cloud Pub/Sub 服务返回以下错误消息，是因为项目 ID 格式有误。

details: 'Project does not exist: example-test-12345'

ExtensionCallout 政策配置中的错误

如果 ExtensionCallout 政策配置错误（可能是政策配置语法错误，也可能是配置键或值不正确），就会出现这些错误。这些错误有两种形式，具体取决于政策的配置方式：

外部资源评估的值不正确

如果配置错误对扩展程序有效，但对外部资源无效，就可能会出现这种情况。例如，如果扩展程序向 Cloud Spanner 传递错误的数据库 ID，Cloud Spanner 会返回一个错误，并将其记录在扩展程序日志中：
```
details: 'Database not found: projects/example-test-123456/instances/spanner-extension-example-db/databases/my-business-d'
```
如果政策的 <Input> 元素中的配置 JSON 不正确，也可能会发生这种情况。对于某些扩展程序，扩展程序会处理 JSON 的一部分，并将另一部分传递给资源。例如，Cloud Logging 扩展配置 JSON 包含一个 metadata 对象，其内容会传递给 Cloud Logging。如果该位置的键名称不正确（例如使用 typ 而非 type），则可能会从外部资源返回错误，这些错误会显示为扩展程序日志中的条目：
```
details: 'Resource type cannot be empty'
```
扩展程序评估的值不正确

这些错误包括 <Input> 元素 JSON 的政策评估部分中的语法错误、<Action> 元素中的操作名称拼写错误等。这些错误通常会显示在跟踪工具中，但不会显示在扩展程序日志中。

Trace 工具中的证据

在代理编辑器中，这些错误通常会显示为 4xx 级或 5xx 级错误。不过，代理编辑器不会显示有关错误原因的任何具体信息，只会说明扩展程序返回了错误。在 Cloud Firestore 扩展程序中拼写错误地输入操作名称时，Trace 工具中会显示以下错误。

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404","detail":
    {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

扩展程序日志中的证据

如果政策配置导致外部资源出现处理错误，该错误通常会显示在日志中。

与扩展程序对资源的请求相关的错误

这是指对外部资源的请求因与扩展程序无关的原因而未成功的错误。

例如，假设您使用 Cloud Spanner 扩展程序向数据库添加了行，但该行的主键值已在现有行中使用。Cloud Spanner 会向扩展程序返回错误，扩展程序会将错误添加到扩展程序日志中。

Trace 工具中的证据

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404",
    "detail":{
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

扩展程序日志中的证据

日志通常包含来自外部资源本身的消息条目。Cloud Spanner 中的以下日志消息介绍了现有的主键值错误。

details: 'Row [jonesy42] in table user already exists'