排查 ADC 设置问题

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

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

用户凭据不起作用

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

Google Cloud API 有两种类型：

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

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

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

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

gcloud auth application-default set-quota-project YOUR_PROJECT

如果您使用 gcloud CLI 来调用 API，则可以在 gcloud CLI 配置中设置配额项目：
```
gcloud config set billing/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 的凭据。如需详细了解这两组凭据，请参阅 gcloud CLI 身份验证配置和 ADC 配置。
确保仅当您使用服务账号密钥或 ADC 的其他 JSON 文件时才设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。该环境变量指向的凭据优先于其他凭据，包括用于 Workload Identity Federation for GKE 的凭据。
确认发出请求的主账号具有所需的 IAM 角色。如果您使用的是用户凭据，则必须向与用户账号关联的电子邮件地址授予这些角色。如果您使用的是服务账号，该服务账号必须具有所需的角色。
如果您在 API 请求中提供 API 密钥，则 API 密钥在任何位置都优先于 ADC。如果您已设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量并且使用的是 API 密钥，则 API 可能会返回一条警告，告知您提供给 ADC 的凭据将予以忽略。如需停止警告，请取消设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

凭据类型无法识别

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

使用范围时访问被阻止

如果您尝试创建本地 ADC 文件，但系统返回类似于“此应用已被屏蔽”或“访问被拒：授权错误”的错误，则表示您可能正在尝试使用默认 ADC 设置命令不支持的范围。通常，此问题是由为 Google Cloud 以外的应用（例如 Google 云端硬盘）添加范围而导致的。

默认情况下，如果访问令牌是从使用用户凭据创建的本地 ADC 文件生成的，则访问令牌会包含云范围 https://www.googleapis.com/auth/cloud-platform。如需明确指定范围，请将 –-scopes 标志与 gcloud auth application-default login 命令结合使用。

如需为 Google Cloud 外部的服务（例如 Google 云端硬盘）添加范围，创建 OAuth 客户端 ID，然后使用 –-client-id-file 标志将其提供给 gcloud auth application-default login 命令，并使用 -–scopes 标志指定范围。