问题排查概览

本页面提供 API Gateway 的一般问题排查信息。

无法运行“gcloud api-gateway”命令

如需运行 gcloud api-gateway ... 命令，您必须已更新 Google Cloud CLI 并启用必要的 Google 服务。如需了解详情，请参阅配置开发环境。

命令“gcloud api-gateway api-configs create”表示服务账号不存在

如果您运行 gcloud api-gateway api-configs create ... 命令并收到以下形式的错误：

ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION:
Service Account "projects/-/serviceAccounts/service_account_email" does not exist

重新运行该命令，但这次包含 --backend-auth-service-account 选项，以明确指定要使用的服务账号的电子邮件地址：

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

确保您已按照配置开发环境中的说明为服务账号分配了必要的权限。

API 请求返回 HTTP 403 错误

如果对已部署 API 的请求向 API 客户端返回 HTTP 403 错误，则表示请求的网址有效，但出于某种原因禁止访问。

部署的 API 具有与授予您在创建 API 配置时使用的服务账号的角色相关联的权限。通常，HTTP 403 错误的原因在于服务账号没有访问后端服务的必要权限。

如果您在同一 Google Cloud 项目中定义了 API 和后端服务，请确保服务帐号分配有 Editor 角色或访问后端服务所需的角色。例如，如果后端服务是使用 Cloud Functions 实现的，请确保该服务账号具有 Cloud Function Invoker 角色。

API 请求返回 HTTP 401 或 500 错误

如果对已部署 API 的请求向 API 客户端返回 HTTP 401 或 500 错误，则可能是在创建 API 配置时使用的服务账号时出现问题。

部署的 API 具有与授予您在创建 API 配置时使用的服务账号的角色相关联的权限。系统会检查服务账号，以确保它都存在，并且可在部署 API 时由 API 网关使用。

如果在部署网关后删除或停用服务账号，则可能会发生以下事件序列：

删除或停用服务账号后，您可能会在网关日志中看到 401 HTTP 响应。如果日志条目的 jsonPayload 中的 response_code_details 字段设置为 "via_upstream"，则表示删除或停用服务账号是错误的原因。
您还可以在 API 网关的日志中看到 HTTP 500 错误，但没有任何相应的日志条目。如果在删除或停用服务账号后没有立即向网关发出请求，则您可能看不到 HTTP 401 响应，但没有相应 API 网关日志的 HTTP 500 错误表示网关的服务账号可能不再有效。

高延迟时间 API 请求

与 Cloud Run 和 Cloud Functions 一样，API Gateway 也会受到“冷启动”延迟的影响。如果您的网关在 15 到 20 分钟内未收到流量，则在冷启动的前 10 到 15 秒内向网关发出的请求将经历 3 到 5 秒的延迟。

如果问题在初始“预热”期结束后仍然存在，请检查您在 API 配置中配置的后端服务的请求日志。例如，如果后端服务是使用 Cloud Functions 实现的，请检查关联 Cloud Function 请求日志的 Cloud Logging 条目。

无法查看日志信息

如果您的 API 响应正确，但日志不包含数据，这通常表示您尚未启用 API Gateway 所需的所有 Google 服务。

API Gateway 要求您启用以下 Google 服务：

名称	标题
`apigateway.googleapis.com`	API Gateway API
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

如需确认已启用必需的服务，请运行以下命令：

gcloud services list

如果您没有看到列出的必需服务，请启用它们：

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

如需详细了解 gcloud 服务，请参阅 gcloud 服务。