问题排查概览

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

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

如需运行 gcloud api-gateway ... 命令,您必须更新 Cloud SDK 并启用必要的 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 Platform (GCP) 中定义了 API 和后端服务,请确保该服务帐号已分配 Editor 角色或具有访问后端服务所需的角色。例如,如果后端服务是使用 Cloud Functions 实现的,请确保该服务帐号具有 Cloud Function Invoker 角色。

API 请求返回 HTTP 401 或 500 错误

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

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

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

  1. 删除或停用服务帐号后,您可能会在网关日志中看到 401 HTTP 响应。如果日志条目的 jsonPayload 中的 response_code_details 字段设置为 "via_upstream",则表示删除或停用服务帐号是错误的原因。

  2. 您还可以在 API 网关的日志中看到 HTTP 500 错误,但没有任何相应的日志条目。如果在删除或停用服务帐号后没有立即向网关发出请求,则您可能看不到 HTTP 401 响应,但没有相应 API 网关日志的 HTTP 500 错误表示网关的服务帐号可能不再有效。

无法查看日志信息

如果您的 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 服务