排查 ADC 设置问题

本页面介绍您在使用应用默认凭据 (ADC) 时可能会遇到的一些常见问题。

如需了解 ADC 的工作原理（包括凭据的位置），请参阅应用默认凭据的工作原理。

用户凭据不起作用

如果 API 请求返回有关 API 不支持用户凭据、项目中未启用 API 或未设置配额项目的错误消息，请查看以下信息。

Google Cloud API 有两种类型：

  • 基于资源的 API，此 API 使用与所访问的资源关联的项目进行结算和配额计算。

  • 基于客户端的 API，此 API 使用与访问资源的账号关联的项目进行结算和配额计算。

如果您提供用户凭据以向基于客户端的 API 进行身份验证，则必须指定用于结算和配额计算的项目。该项目称为“配额项目”。

您可以通过多种方式指定配额项目，包括以下选项：

  • 更新 ADC 以使用其他项目作为配额项目：

    gcloud auth application-default set-quota-project YOUR_PROJECT

  • 如果您直接调用 REST 或 RPC API，请使用 x-goog-user-project HTTP 标头在每个请求中指定配额项目。如需了解详情，请参阅通过 REST 请求设置配额项目。

您必须拥有项目的 serviceusage.services.use IAM 权限才能将其指定为结算项目。Service Usage Consumer IAM 角色可提供 serviceusage.services.use 权限。如果您没有任何项目的 serviceusage.services.use 权限，请与您的安全管理员或项目所有者联系，他们可以为您授予项目的 Service Usage Consumer 角色。

如需详细了解配额项目，请参阅配额项目概览。如需了解设置配额项目的其他方法，请参阅设置配额项目。

凭据不正确

如果您的凭据似乎没有提供您预期的访问权限，或者找不到您的凭据，请检查以下内容：

  • 如果您使用 gcloud CLI 在本地环境中访问 Google Cloud，请务必了解您正在使用的凭据。使用 gcloud CLI 时，您使用通过 gcloud auth login 命令提供给 gcloud CLI 的凭据。您未使用提供给 ADC 的凭据。如需详细了解这两组凭据，请参阅 ADC 凭据和 gcloud 凭据。

  • 确保仅当您使用服务账号密钥或 ADC 的其他 JSON 文件时才设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。该环境变量指向的凭据优先于其他凭据，包括用于 Workload Identity 的凭据。

  • 确认发出请求的主账号具有所需的 IAM 角色。如果您使用的是用户凭据，则必须向与 Google 账号关联的电子邮件地址授予这些角色。如果您使用的是服务账号，该服务账号必须具有所需的角色。

  • 如果您在 API 请求中提供 API 密钥，则 API 密钥在任何位置都优先于 ADC。如果您已设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量并且使用的是 API 密钥，则 API 可能会返回一条警告，告知您提供给 ADC 的凭据将予以忽略。如需停止警告，请取消设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

凭据类型无法识别

如果 API 请求返回包含“从 JSON 创建凭据时出错。凭据类型无法识别”的错误，请确保您使用的是有效凭据。系统不支持使用客户端 ID 文件为 ADC 提供凭据。