排查响应错误

本页介绍如何排查 API 请求响应中返回的错误。

BAD_GATEWAY

如果您收到错误代码 13 和消息 BAD_GATEWAY，这表示 Extensible Service Proxy (ESP) 无法访问服务的后端。 请检查以下各项：

  • 确保后端服务正在运行。具体的操作方法取决于后端。

  • 已为后端服务指定正确的 IP 地址端口：
    • 对于 GKE，检查部署清单文件（通常称为 deployment.yaml）中的 ESP --backend 标志值（短选项为 -a）。
    • 对于 Compute Engine，检查 docker run 命令中的 ESP --backend 标志值（短选项为 -a）。

reset reason: connection failure

如果您收到 HTTP 代码 503 或 gRPC 代码 14 和消息 upstream connect error or disconnect/reset before headers. reset reason: connection failure，这表示 ESPv2 无法访问服务的后端。

如要进行问题排查，请仔细检查以下各项内容。

后端地址

您应使用正确的后端地址配置 ESPv2。常见问题包括：

  • 后端地址方案应与后端应用类型相匹配。OpenAPI 后端应为 http://，而 gRPC 后端应为 grpc://。
  • 对于部署在 Cloud Run 上的 ESPv2，后端地址方案应为 https:// 或 grpcs://。s 指示 ESPv2 使用后端设置 TLS。

DNS 查找

默认情况下，ESPv2 会尝试将域名解析为 IPv6 地址。如果 IPv6 解析失败，ESPv2 会回退为 IPv4 地址。

对于某些网络，后备机制可能无法按预期运行。您可以改为通过 --backend_dns_lookup_family 标志强制 ESPv2 使用 IPv4 地址。

如果您为 Cloud Run 上部署的 ESPv2 配置无服务器 VPC 连接器，则此错误很常见。VPC 不支持 IPv6 流量。

API is not enabled for the project

如果您在请求中发送了 API 密钥，但收到类似“没有为项目启用 API my-api.endpoints.example-project-12345.cloud.goog”的错误消息，则表示 API 密钥是在与 API 不同的 Google Cloud 项目中创建的。如需解决此问题，您可以在与 API 关联的同一 Google Cloud 项目中创建 API 密钥，也可以在创建了 API 密钥的 Google Cloud 项目中启用 API。

Service control request failed with HTTP response code 403

如果您收到错误代码 14 和消息 Service control request failed with HTTP response code 403，这表示该项目未启用 Service Control API (servicecontrol.googleapis.com)。

  1. 请参阅检查所需服务，确保在项目中启用了 Endpoints 和 ESP 所需的所有服务。

  2. 请参阅检查所需权限，以确保与运行 ESP 的实例关联的服务账号所需的所有权限。

Method doesn't allow unregistered callers

如果您在 OpenAPI 文档的 security 部分中指定了 API 密钥，但是向 API 发送的请求中未包含分配给名为 key 的查询参数的 API 密钥，则 ESP 会返回错误 Method doesn't allow unregistered callers 作为响应。

如果您需要生成 API 密钥以调用 API，请参阅创建 API 密钥。

Method does not exist

响应 Method does not exist 意味着在指定网址路径上找不到 HTTP 方法（GET、POST 或其他）。如需排查此问题，请比较已部署的服务配置，确保方法名称与您在请求中发送的网址路径匹配：

  1. 在 Google Cloud 控制台中，前往项目的 Endpoints 服务页面。

    转到“Endpoints 服务”页面

  2. 如果您有多个 API，请选择您向其发送了请求的 API。

  3. 点击部署记录标签。

  4. 选择最新的部署以查看服务配置。

如果您在 OpenAPI 文档的 paths 部分中没有看到要调用的方法，请添加该方法，或在文件顶层添加 x-google-allow 标志：

x-google-allow: all

此标志表示，您不必在 OpenAPI 文档中列出后端支持的所有方法。如果使用 all，则所有调用（无论是否使用 API 密钥或用户身份验证）都会通过 ESP 传递给您的 API。请参阅 x-google-allow 。

App Engine 柔性环境特有错误

本部分介绍来自部署在 App Engine 柔性环境中的 API 的错误响应。

错误代码 502 或 503

App Engine 可能需要几分钟时间才能成功响应请求。 如果您在发送请求后收到 HTTP 502、503 或其他一些服务器错误，请稍等一下再重新发送请求。

错误消息 BAD_GATEWAY

如果您收到错误代码 502 和消息 BAD_GATEWAY，这通常表示 App Engine 因内存不足而终止了应用。 默认的 App Engine 柔性虚拟机只有 1GB 内存，并且仅 600MB 内存可用于应用容器。

要排查错误代码 502 的问题，请执行以下操作：

  1. 在 Google Cloud 控制台中，转到日志记录页面：

    转到“日志浏览器”页面

  2. 在页面顶部选择适用的 Google Cloud 项目。

  3. 选择 Google App Engine 应用，并打开 vm.syslog。

  4. 查找如下日志条目：

    kernel: [  133.706951] Out of memory: Kill process 4490 (java) score 878 or sacrifice child
kernel: [  133.714468] Killed process 4306 (java) total-vm:5332376kB, anon-rss:2712108kB, file-rss:0kB

    如果您在日志中看到 Out of memory 条目，请执行以下操作：

    1. 将以下内容添加到 app.yaml 文件中，以增加默认虚拟机的大小：

      resources:
  memory_gb: 4

    2. 重新部署您的 API：

      gcloud app deploy

如果您在 app.yaml 文件的 endpoints_api_service 部分中指定了 rollout_strategy: managed 选项，请使用以下命令重新部署您的 API：

  gcloud app deploy

如需了解详情，请参阅部署 API 和 ESP。

检查 Cloud Logging 日志

如需借助 Cloud 日志来排查响应错误，请执行以下操作：

  1. 在 Google Cloud 控制台中，转到 Logging 页面。

    转到“日志浏览器”页面

  2. 在页面顶部，选择 Google Cloud 项目。

  3. 使用左侧下拉菜单，选择 Produced API > [YOUR_SERVICE_NAME]。

  4. 调整时间范围，直到出现显示相关响应错误的行。

  5. 展开 JSON 载荷并查找 error_cause。

    • 如果 error_cause 设置为 application，这表示代码中存在问题。

    • 如果 error cause 为其他内容，并且您无法解决问题，请导出日志并将其附在您与 Google 的通信中。

请参阅以下内容了解详细信息：

示例 Invoke-WebRequest 的问题

在某些版本的 Windows PowerShell 中，Invoke-WebRequest 教程 失败。我们还收到了一份报告，显示响应包含无符号字节列表，这些无符号字节必须转换为字符。如果示例 Invoke-WebRequest 未返回预期的结果，请尝试使用其他应用发送请求。下面是一些建议：

  • 启动 Cloud Shell，并按照教程中指导您发送请求的 Linux 系统步骤操作。

  • 安装 Chrome 浏览器扩展程序 Postman（由 www.getpostman.com 提供）等第三方应用。在 Postman 中创建请求时，请确保以下几点：

    • 选择 POST 作为 HTTP 谓词。
    • 对于标头，请选择键 content-type 和值 application/json。
    • 对于正文，请输入：{"message":"hello world"}

    • 在网址中，使用实际的 API 密钥，而非环境变量。例如：

      • 在 App Engine 柔性环境中：https://example-project-12345.appspot.com/echo?key=AIza...
      • 在其他后端中：http://192.0.2.0:80/echo?key=AIza...

  • 下载并安装要在命令提示符中运行的 curl。由于 Windows 不处理单引号内嵌套的双引号，因此您必须将示例中的 --data 选项更改为：

    --data "{\"message\":\"hello world\"}"