排查响应错误

OpenAPI | gRPC

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

`BAD_GATEWAY`

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

确保后端服务正在运行。具体的操作方法取决于后端。
- 对于 App Engine 柔性环境，BAD_GATEWAY 消息对应的错误代码可能是 502。如需了解详情，请参阅 App Engine 柔性环境特有错误部分。
- 对于 Compute Engine，请参阅排查 Compute Engine 上的 Cloud Endpoints 问题了解详情。
- 对于 GKE，您需要通过 SSH 来访问 pod 和使用 curl。如需了解详情，请参阅排查 Google Kubernetes Engine 中的 Endpoints 问题。

已为后端服务指定正确的 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)。

请参阅检查所需服务，确保在项目中启用了 Endpoints 和 ESP 所需的所有服务。
请参阅检查所需权限，以确保与运行 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 或其他）。如需排查此问题，请比较已部署的服务配置，确保方法名称与您在请求中发送的网址路径匹配：

在 Google Cloud 控制台中，转到项目的 端点服务页面。
转到“Endpoints 服务”页面
如果您有多个 API，请选择您向其发送了请求的 API。
点击部署记录标签。
选择最新的部署以查看服务配置。

如果您在 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 的问题，请执行以下操作：

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

转到“日志浏览器”页面
在页面顶部选择适用的 Google Cloud 项目。
选择 Google App Engine 应用，并打开 vm.syslog。

查找如下日志条目：

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 条目，请执行以下操作：

将以下内容添加到 app.yaml 文件中，以增加默认虚拟机的大小：
```
resources:
  memory_gb: 4
```
重新部署您的 API：
```
gcloud app deploy
```

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

  gcloud app deploy

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

检查 Cloud Logging 日志

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

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

转到“日志浏览器”页面
在页面顶部，选择 Google Cloud 项目。
使用左侧下拉菜单，选择 Produced API > [YOUR_SERVICE_NAME]。
调整时间范围，直到出现显示相关响应错误的行。
展开 JSON 载荷并查找 error_cause。
- 如果 error_cause 设置为 application，这表示代码中存在问题。
- 如果 error cause 为其他内容，并且您无法解决问题，请导出日志并将其附在您与 Google 的通信中。

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

如需详细了解日志浏览器中的日志结构，请参阅 Endpoint 日志参考文档
开始使用日志浏览器。
使用高级日志查询执行高级过滤，例如查看延迟时间超过 300 毫秒的所有请求。

示例 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\"}"
```

排查响应错误

BAD_GATEWAY

reset reason: connection failure

后端地址

DNS 查找

API is not enabled for the project

Service control request failed with HTTP response code 403

Method doesn't allow unregistered callers

Method does not exist