[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-18。"],[[["\u003cp\u003eA quota project must be identified for requests to client-based APIs to succeed, and the order of precedence for identifying the quota project is environment/request, API key, gcloud CLI, service account, and workforce identity federation user.\u003c/p\u003e\n"],["\u003cp\u003eThe quota project can be set programmatically, via environment variables, or using authentication credentials, and programmatic setting overrides all other methods.\u003c/p\u003e\n"],["\u003cp\u003eTo use a project as a quota project, the user needs the \u003ccode\u003eroles/serviceusage.serviceUsageConsumer\u003c/code\u003e IAM role, which contains the \u003ccode\u003eserviceusage.services.use\u003c/code\u003e permission, on that project.\u003c/p\u003e\n"],["\u003cp\u003eSome APIs also limit requests per user, where the authenticated principal or client IP address is used by default, unless the \u003ccode\u003equotaUser\u003c/code\u003e parameter is specified, which requires a valid API key with IP restrictions.\u003c/p\u003e\n"],["\u003cp\u003eYou can set the quota project programmatically with client options, gcloud CLI configurations, or the \u003ccode\u003ex-goog-user-project\u003c/code\u003e header in a REST request.\u003c/p\u003e\n"]]],[],null,["# Set the quota project\n\nThis document describes how to set a quota project for your\n[client-based APIs.](/docs/quotas/quota-project#project-client-based)\nFor information about what the quota project\nis, how to set the quota API, and how the quota project is determined,\nsee [About the quota project.](/docs/quotas/quota-project)\n\nRequests can fail if you make a request to a client-based API and the quota\nproject cannot be identified. The quota project can be set in multiple ways and\nis verified by checking the following options. They appear in the order of\nprecedence:\n\n- **Specified in request** : The quota project that was specified in the\n [request](/docs/quotas/set-quota-project#set-project-programmatically).\n (When using client libraries, you can also use [environment\n variables](/docs/quotas/set-quota-project#set-project-variable)\n in your requests.)\n\n- **API key**: If you use an API key to provide credentials for a\n request, the project associated with the API key is used as the quota\n project.\n\n- **Google Cloud CLI credentials**: If you use the gcloud CLI\n to get your access token, and you've authenticated to the\n gcloud CLI with your user credentials, the gcloud CLI\n shared project is sometimes used as the quota project. However, not all\n client-based APIs fall back on the shared project.\n\n- **Service account**: If the principal for the API call is a service\n account, including by impersonation, the project associated with the service\n account is used as the quota project.\n\n- **Workforce identity federation** : If the principal for the API is a\n workforce identity federation user, the\n [workforce pools user project](/iam/docs/workforce-identity-federation#workforce-pools-user-project)\n is used as the quota project.\n\nIf none of the previous checks yield a quota project, the request fails.\n\nThere are several ways to set quota projects. If the quota project is specified\nby more than one method, the following precedence is applied:\n\n1. Programmatically\n2. Environment variable\n3. Credentials used to authenticate the request\n\nSet the quota project programmatically\n--------------------------------------\n\nYou can explicitly set the quota project in your application. This method\noverrides all other definitions. The [principal](/docs/authentication#principal)\nused to authenticate the request must have the required permission on the\nspecified quota project.\n\nHow you set the quota project programmatically depends on whether\nyou're using a client library, the gcloud CLI, or REST API request.\n\n### Client library\n\nYou can set the value for the quota project by using client options when you\ncreate the client. This method works well if you want to control the value for\nyour quota project from your application, regardless of what environment it's\nrunning in.\n\nFor more information about implementing client options, see your client library\ndocumentation.\n\n### gcloud CLI\n\nYou can set the quota project for all gcloud CLI commands by using\nthe `billing/quota_project` property in your gcloud CLI configuration. You can\nalso set the quota project for a specific command by using the `--billing-project`\nflag, which takes precedence over the configuration property.\n\nFor more information about `gcloud` CLI configurations, see the\n[`gcloud config` documentation](/sdk/gcloud/reference/config).\nFor more information about the `--billing-project` flag, see the\n[`--billing-project` documentation](/sdk/gcloud/reference#--billing-project).\n\n### REST request\n\nYou can specify the quota project in a REST request using the\n[`x-goog-user-project` header.](/apis/docs/system-parameters#definitions)\nThe principal making the request must have the required permissions on the quota\nproject.\n\nFor more information and sample code, see\n[Set the quota project with a REST request](/docs/authentication/rest#set-billing-project).\n\nSet the quota project using an environment variable\n---------------------------------------------------\n\nClient libraries for some languages support setting the quota project using an\nenvironment variable. This approach can be helpful if you want to set the quota\nproject differently in different shells, or to override the quota project\nassociated with the credential. The principal for any request must have the\nrequired permissions on the quota project specified by the environment variable.\n\nThe environment variable is language dependent:\n\nSet the quota project using authentication credentials\n------------------------------------------------------\n\nIf the quota project isn't specified, the authentication libraries try to\ndetermine it from the credentials that were used for the request. This process\ndepends on the type of credentials that were used to authenticate the request:\n\n- **Service account** -- The project associated with the service account is used as the quota project.\n- **User credentials** -- For a local development environment, [Application Default Credentials](/docs/authentication/application-default-credentials) finds your user credentials from the local ADC file. That file can also specify a quota project. If you have the project set in your Google Cloud CLI config, and you have the required permissions on that project, the quota project is set by default when you create the local ADC file. You can also set the ADC quota project by using the [`auth application-default set-quota-project` command.](/sdk/gcloud/reference/auth/application-default/set-quota-project)\n- **API keys** -- When you use an API key to provide credentials for a request, the project associated with the API key is used as the quota project.\n\nPermissions required to set and use the quota project\n-----------------------------------------------------\n\n\nTo get the permission that\nyou need to set a project as the quota project, or use that quota project in a request,\n\nask your administrator to grant you the\n\n\n[Service Usage Consumer](/iam/docs/roles-permissions/serviceusage#serviceusage.serviceUsageConsumer) (`roles/serviceusage.serviceUsageConsumer`)\nIAM role on the project.\n\n\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\nThis predefined role contains the\n` serviceusage.services.use`\npermission,\nwhich is required to\nset a project as the quota project, or use that quota project in a request.\n\n\nYou might also be able to get\nthis permission\nwith [custom roles](/iam/docs/creating-custom-roles) or\nother [predefined roles](/iam/docs/roles-overview#predefined).\n\nIf you use a project you created as your quota project, you have the necessary\npermissions.\n\nFor more information about permissions, see [Quota permissions](/docs/quotas/permissions).\n\nSet the quota user\n------------------\n\nSome APIs also limit the number of requests per user, which is different from\nthe per project quotas described in prior sections of this document.\n\nBy default, the system uses the authenticated principal. If there is no\nauthenticated principal, the system uses the client IP address.\n\nIf you need to override the quota user, you can set the `quotaUser` parameter\nthrough the Cloud API [System parameters](/apis/docs/system-parameters). If you\ndo specify a `quotaUser` or `X-Goog-Quota-User`, a valid API key with IP address\nrestrictions must be used to identify the quota project. Otherwise, the\n`quotaUser` parameter is ignored.\n\nTo learn more about Cloud API system parameters and their definitions, see the\nsystem parameters [definitions table](/apis/docs/system-parameters#definitions).\n\nWhat's next\n-----------\n\n- About the [quota project](/docs/quotas/quota-project)\n- Learn more about [Application Default Credentials](/docs/authentication/application-default-credentials)\n- Get more information about [authentication](/docs/authentication)\n- Understand [quotas](/docs/quotas/overview)"]]
