设置配额项目

本页面介绍了如何为基于客户端的 API 设置配额项目。如需了解配额项目是什么,如何设置配额 API,以及如何确定配额项目,请参阅配额项目简介

向基于客户端的 API 发出请求时,如果无法识别配额项目,则请求会失败。

配额项目可以采用多种方式设置,系统会通过检查以下选项来验证项目。列出的顺序是优先顺序。

  • 环境请求中设置的配额项目。
  • 如果您使用 API 密钥为请求提供凭据,则与 API 密钥关联的项目将用作配额项目。
  • 如果您使用 Google Cloud CLI 获取访问令牌,并且已使用用户凭据向 gcloud CLI 进行身份验证,则 gcloud CLI 共享项目有时用作配额项目。 并非所有基于客户端的 API 都依赖于共享项目。
  • 如果 API 调用的主账号是服务账号(包括通过模拟),则与服务账号关联的项目将用作配额项目。
  • 如果 API 的主账号是员工身份联合用户,则系统会将员工池用户项目用作配额项目。

如果以上检查均未产生配额项目,则请求失败。

您可以通过多种方式设置配额项目。如果配额项目由多个方法指定,则应用以下优先级:

  1. 以编程方式
  2. 环境变量
  3. 用于对请求进行身份验证的凭据

以编程方式设置配额项目

您可以在应用中明确设置配额项目。此方法会替换所有其他定义。用于对请求进行身份验证的主账号必须具有指定配额项目所需的权限。

以编程方式设置配额项目的方式取决于您使用的是客户端库、gcloud CLI 还是 REST 请求。

客户端库

您可以在创建客户端时使用客户端选项来设置配额项目的值。如果您想要从应用控制配额项目的值(无论它在什么环境中运行),则此方法非常适用。

如需详细了解如何实现客户端选项,请参阅客户端库文档。

gcloud CLI

您可以使用 gcloud CLI 配置中的 billing/quota_project 属性为所有 gcloud CLI 命令设置配额项目。您还可以使用 --billing-project 标志(该配置优先于配置属性)为特定命令设置配额项目。

如需详细了解 gcloud CLI 配置,请参阅 gcloud 配置参考页面。如需详细了解 --billing-project 标志,请参阅全局标志参考文档

REST 请求

您可以使用 x-goog-user-project 标头在 REST 请求中指定配额项目。发出请求的主账号必须具有配额项目所需的权限。

如需了解详情和示例代码,请参阅通过 REST 请求设置配额项目

使用环境变量设置配额项目

某些语言的客户端库支持使用环境变量设置配额项目。如果您想在不同 shell 中以不同方式设置配额项目,或者替换与凭据关联的配额项目,此方法会非常有用。任何请求的主账号都必须对环境变量指定的配额项目具有所需权限。

环境变量取决于语言:

语言 环境变量
C++

GOOGLE_CLOUD_CPP_USER_PROJECT

C#

GOOGLE_CLOUD_QUOTA_PROJECT

Go

GOOGLE_CLOUD_QUOTA_PROJECT

Java

GOOGLE_CLOUD_QUOTA_PROJECT

Node.js

GOOGLE_CLOUD_QUOTA_PROJECT

Python

GOOGLE_CLOUD_QUOTA_PROJECT

PHP

GOOGLE_CLOUD_QUOTA_PROJECT

Ruby 不可用

使用身份验证凭据设置配额项目

如果未指定配额项目,则身份验证库会尝试从用于请求的凭据来进行确定。此过程取决于用于对请求进行身份验证的凭据类型:

  • 服务账号 - 与服务账号关联的项目用作配额项目。
  • 用户凭据 - 对于本地开发环境,应用默认凭据会从本地 ADC 文件中查找用户凭据。该文件也可以指定配额项目。如果您在 Google Cloud CLI 配置中设置了配额项目,并且您拥有该项目所需的权限,则当您创建本地 ADC 文件时,系统会默认设置配额项目。您还可以使用 auth application-default set-quota-project 命令设置 ADC 配额项目。
  • API 密钥 - 使用 API 密钥为请求提供凭据时,系统会将与 API 密钥关联的项目用作配额项目。

设置和使用配额项目所需的权限

如需获得将项目设置为配额项目所需的权限,或者在请求中使用该配额项目,请让管理员向您授予以下权限:项目的 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) IAM 角色。 如需详细了解如何授予角色,请参阅管理访问权限

此预定义角色包含 serviceusage.services.use 权限,要将项目设置为配额项目或在请求中使用该配额项目,必须具有该权限。

您也可以使用自定义角色或其他预定义角色来获取此权限。

如果您使用自己创建的项目作为配额项目,那么您已拥有必要的权限。

如需详细了解权限,请参阅配额权限

设置配额用户

某些 API 还限制了每个用户的请求数,这与本页前面部分中介绍的每个项目的配额不同。

默认情况下,系统使用经过身份验证的主账号。如果没有经过身份验证的主账号,系统会使用客户端 IP 地址。

如果您需要替换配额用户,则可以通过 Cloud API 系统参数设置 quotaUser 参数。如果您指定了 quotaUserX-Goog-Quota-User,则必须使用具有 IP 地址限制的有效 API 密钥来标识配额项目。否则,系统会忽略 quotaUser 参数。

如需详细了解 Cloud API 系统参数及其定义,请参阅系统参数定义表

后续步骤