调试扩展程序

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

您可以使用在跟踪工具和扩展程序日志这两个位置显示的消息来调试扩展程序。当某个扩展程序无法正常运行时，要找出问题所在，有时需要从这两个位置获得信息。

  • 借助 Apigee Edge 跟踪工具，您可以在开发 API 代理代码时以迭代方式测试和修改 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 会向该扩展程序返回错误。这些错误的详细信息通常位于扩展程序日志中。

跟踪工具中的证据

在代理编辑器中，这些错误通常显示为 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 政策配置有误，要么是因为政策配置语法错误，要么是因为配置键或值不正确。此类错误有两种形式，具体取决于政策的配置方式：

  • 外部资源评估的值不正确

    当配置错误对扩展程序有效，但对外部资源无效时，就会发生这种情况。例如，如果扩展程序将错误的数据库 ID 传递给 Cloud Spanner，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> 元素中的操作名称拼写错误等等。这些错误通常会显示在跟踪工具中，但不会出现在扩展程序日志中。

跟踪工具中的证据

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

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

扩展程序日志中的证据

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

此错误表示对外部资源的请求失败，原因与扩展程序无关。

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

跟踪工具中的证据

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

{
  "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'