问题排查概览

本页面提供 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 \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

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

确定 API 错误响应的来源

如果对已部署 API 的请求导致错误（HTTP 状态代码 400 到 599），则可能无法从响应本身中清楚地看出错误是源自网关还是后端。 如需确定这一点，请执行以下操作：

  1. 前往 Logs Explorer 页面，然后选择您的项目。

    前往 Logs Explorer

  2. 使用以下日志查询过滤到相关的网关资源：

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"

    其中：

    • GATEWAY_ID 指定网关的名称。
    • GCP_REGION 是已部署网关的 Google Cloud 区域。

  3. 找到与您要调查的 HTTP 错误响应匹配的日志条目。 例如，按 httpRequest.status 进行过滤。

  4. 检查 jsonPayload.responseDetails 字段的内容。

如果 jsonPayload.responseDetails 字段的值为 "via_upstream"，则表示错误响应源自您的 后端，您需要直接排查后端的问题。如果是任何其他值，则表示错误响应源自网关；如需了解更多问题排查提示，请参阅本文档的以下部分。

API 请求返回 HTTP 403 错误

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

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

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

API 请求返回 HTTP 401 或 500 错误

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

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

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

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

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

如果失败请求的后端是另一个 Google Cloud API（例如 bigquery.googleapis.com），您将在网关日志中看到 401 HTTP 响应 ，并且 jsonPayload.responseDetails 字段设置为 "via_upstream"。这是因为 API Gateway 使用 ID 令牌向后端进行身份验证，而 其他 Google Cloud API 需要 访问令牌。

API 请求针对强制执行配额的方法返回 HTTP 500 错误

如果您收到以下错误，则表示网关无法为您的请求分配配额：

HTTP/2 500
{"code":500,"message":"Failed to call Service Control Quota."}

当您调用配置了 配额的方法，但该 API 的配额指标不再存在时，通常会发生此错误。在 gRPC 网关上，系统会返回相同的失败，即 gRPC 状态代码 Internal。

在网关日志中确认原因

  1. 前往 Logs Explorer 页面，然后选择您的项目。

    前往 Logs Explorer

  2. 运行以下日志查询：

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500

    其中，GATEWAY_ID 指定网关的名称。

    该查询会根据状态代码以及 jsonPayload.responseDetails进行过滤，因为 API Gateway 对每个配额拒绝使用 相同的 responseDetails值。合法超出配额的请求会生成相同的值，并且 httpRequest.status 为 429。

  3. 检查任何匹配条目的 jsonPayload.apiConfig 和 jsonPayload.apiMethod 字段。它们用于标识 API 配置和方法，其配额配置无效。

API 配置为何可能具有无效的配额配置

您可以在 API 配置中定义配额指标和限制，但 API Gateway 会将它们应用于整个 API。每次创建 API 配置时，它声明的指标和限制都会替换 API 的先前 API 配置声明的指标和限制。 系统只会强制执行最近创建的 API 配置中的值。

相比之下，每个方法使用的指标是在网关处理的 API 配置中定义的。如果网关运行的是较旧的 API 配置，它会要求 Service Control 根据其自身配置中存在的指标分配配额，但该指标可能不存在于 API 中。如果该指标不存在，则分配调用会失败，并且网关会拒绝该请求。

例如，以下序列会导致第一个网关出现故障：

  1. 您创建 API 配置 config-v1，该配置声明了指标 quota-metric-v1，并将其部署到 gateway-1。
  2. 您为同一 API 创建 API 配置 config-v2，该配置声明了指标 quota-metric-v2，并将其部署到 gateway-2。

gateway-2 可以正常运行，但对 gateway-1 的强制执行配额的方法的请求开始失败，因为不再为 API 定义 quota-metric-v1。

以下更改可能会导致仍使用较旧 API 配置部署的任何网关出现错误：

  • 重命名或移除指标。
  • 更改配额限制所适用的指标。
  • 更改按方法配额费用中命名的指标（OpenAPI 文档为 x-google-quota，gRPC 服务配置为 quota.metric_rules）。

仅更改限制的值不会导致错误。 但是，由于限制也应用于 API 级别，因此系统会在该 API 的每个网关（包括使用较旧 API 配置部署的网关）上强制执行新值。

比较已部署的配额配置

  1. 列出您的网关以及每个网关处理的 API 配置：

    gcloud api-gateway gateways list \
 --format="table(name.basename(),apiConfig)"

  2. 列出受影响 API 的 API 配置，最近创建的配置排在最前面：

    gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"

    第一个条目是 API 配置，其配额指标和限制针对整个 API 强制执行。使用 --format 标志进行排序，如图所示：此命令不支持 --sort-by 标志，并且不会以可预测的顺序返回 API 配置。

  3. 显示创建 API 配置所依据的 API 定义：

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode

    需要使用 tr 命令，因为 contents 字段采用 base64url 编码，base64 --decode 无法直接读取 。

    对于 gRPC API，配额配置位于服务配置中，而不是 OpenAPI 文档中，因此请将 openapiDocuments[0].document.contents 替换为 managedServiceConfigs[0].contents。

  4. 针对第 2 步中列表顶部的 API 配置运行第 3 步中的命令，然后针对第 1 步中显示为仍部署到网关的每个其他 API 配置运行该命令。

  5. 比较结果。较旧 API 配置针对其方法收取的每个指标也必须在最近创建的 API 配置中定义。如果该配置中缺少某个指标，则处理较旧 API 配置的网关会失败。

恢复有效的配额配置

审核您的配额指标和限制，以确保它们在所有有效配置中保持一致。为此，请执行以下操作之一：

  • 更新 API 的每个网关，以使用最近创建的 API 配置， 如更新网关中所述。
  • 创建一个新的 API 配置，该配置声明了仍部署的 API 配置使用的每个指标，并使现有网关保留在其当前的 API 配置上。

为避免分配错误，请确保 API 的 API 配置中的指标名称保持一致。更改配额时，请更改限制的值，而不是指标的名称。

高延迟 API 请求

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

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

无法查看日志信息

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

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

名称 服务名称
API Gateway API apigateway.googleapis.com
Service Management API servicemanagement.googleapis.com
Service Control API servicecontrol.googleapis.com

如需启用必需服务，请执行以下操作：

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，前往 API 和服务 > API 库 页面。

    前往 API 库

  2. 在 API 库 页面上，在搜索栏中输入所需 API 的名称。
  3. 在搜索结果中，选择 API 页面。
  4. 在 API 页面上，点击启用 。
  5. 针对上表中列出的每项服务重复执行这些步骤。

Google Cloud CLI

使用以下命令启用服务：

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

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