할당량 프로젝트가 결정되는 방법은 사용하는 API 메서드 유형(리소스 기반 API 또는 클라이언트 기반 API)에 따라 다릅니다. 드물지만 서비스에 두 가지 유형의 API 메서드가 모두 있을 수 있습니다.
리소스 기반 API
리소스 기반 Cloud API의 경우 API 호출에 할당량을 제공하는 프로젝트는 액세스되는 리소스를 포함하는 프로젝트이기도 합니다. 예를 들어 Compute Engine 인스턴스를 만들 때 이 새 인스턴스의 프로젝트를 지정해야 합니다. 그러면 프로젝트에 새로 생성된 인스턴스가 포함됩니다. 나중에 Compute Engine 인스턴스에서 작업을 수행하면 인스턴스가 포함된 프로젝트가 요청의 할당량을 제공합니다. 이는 Google Cloud CLI, REST API 또는 클라이언트 라이브러리 사용 여부에 관계없이 적용됩니다.
리소스 기반 API에 대한 요청에 사용되는 할당량 프로젝트는 변경할 수 없습니다.
요청은 항상 요청이 작동하는 리소스가 포함된 프로젝트를 사용합니다.
클라이언트 기반 API
API가 리소스 기반 API가 아니면 클라이언트 기반 API입니다. 예를 들어 Cloud Translation API는 일반적으로 사용되는 클라이언트 기반 API입니다.
클라이언트 기반 API에 대한 요청을 수행할 때 할당량 프로젝트를 식별할 수 없으면 요청이 실패할 수 있습니다. 할당량 프로젝트는 여러 방법으로 설정할 수 있으며 다음 옵션을 확인하여 인증됩니다. 다음과 같은 우선순위 순서로 표시됩니다.
요청에 지정됨: 요청에 지정된 할당량 프로젝트입니다.
(클라이언트 라이브러리를 사용하는 경우 요청에서 환경 변수를 사용할 수도 있습니다.)
API 키: API 키를 사용하여 요청의 사용자 인증 정보를 제공하는 경우 API 키와 연결된 프로젝트가 할당량 프로젝트로 사용됩니다.
Google Cloud CLI 사용자 인증 정보: gcloud CLI를 사용하여 액세스 토큰을 가져오고 사용자 인증 정보로 gcloud CLI에 인증한 경우 gcloud CLI 공유 프로젝트가 할당량 프로젝트로 사용되는 경우도 있습니다. 다만, 모든 클라이언트 기반 API가 공유 프로젝트를 사용하는 것은 아닙니다.
서비스 계정: 가장에 의한 경우를 포함하여 API 호출의 주 구성원이 서비스 계정인 경우 해당 서비스 계정과 연결된 프로젝트가 할당량 프로젝트로 사용됩니다.
직원 ID 제휴: API의 주 구성원이 직원 ID 제휴 사용자인 경우 직원 풀 사용자 프로젝트가 할당량 프로젝트로 사용됩니다.
앞의 검사 중 어느 것도 할당량 프로젝트를 생성하지 않으면 요청이 실패합니다.
클라이언트 기반 API용 gcloud CLI 공유 프로젝트 정보
할당량 프로젝트를 설정하지 않고 gcloud CLI를 사용하여 클라이언트 기반 API에 요청을 전송하는 경우 gcloud CLI 공유 프로젝트로 대체되거나 요청이 실패할 수 있습니다. gcloud CLI 공유 프로젝트는 모든 프로젝트의 모든 gcloud CLI 요청에서 사용되므로, 다른 여러 gcloud CLI 요청도 이 프로젝트를 할당량 프로젝트로 사용하는 경우 공유 프로젝트의 할당량이 일시적으로 고갈될 수 있습니다. 이 경우 할당량 초과 오류 메시지가 표시되고 요청이 실패합니다.
클라이언트 기반 API의 현재 할당량 프로젝트 식별
할당량 프로젝트를 식별하는 방법은 프로젝트가 구성된 방식에 따라 다릅니다.
리소스 기반 API를 사용하도록 API 메서드가 구성된 경우 클라이언트 프로젝트는 리소스 프로젝트를 할당량 프로젝트로 사용합니다.
사용 중인 API 유형을 파악하기가 어려울 수 있습니다. 그러나 활성화 및 할당량은 동일한 방식으로 적용됩니다. 예를 들어, 프로젝트 A의 서비스 계정이 프로젝트 B의 읽기 메서드를 호출하고 두 프로젝트 모두에 API가 사용 설정되지 않은 경우 API not enabled 오류 메시지는 활성화가 확인된 프로젝트를 나타냅니다. 활성화를 확인한 프로젝트는 비율 할당량을 확인한 프로젝트와 동일합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eEvery Google Cloud API request requires a quota project, which is the project used for quota enforcement and is sometimes also referred to as the billing project.\u003c/p\u003e\n"],["\u003cp\u003eFor resource-based APIs, the quota project is always the project that contains the resource being accessed, and this cannot be changed.\u003c/p\u003e\n"],["\u003cp\u003eFor client-based APIs, the quota project is determined by a hierarchy of options, such as the environment variable, API key association, gcloud CLI shared project, or the project associated with the service account or workforce identity federation user.\u003c/p\u003e\n"],["\u003cp\u003eIf no quota project is identified for a client-based API request, the request will fail, highlighting the importance of setting the quota project correctly.\u003c/p\u003e\n"],["\u003cp\u003eThe gcloud CLI may fall back on the "gcloud CLI shared project" if a quota project is not set, but this can lead to quota depletion and request failures.\u003c/p\u003e\n"]]],[],null,["# Quota project overview\n\nThis document describes the *quota project* and how the quota project is\ndetermined. Make sure that your quota project is set correctly to help avoid\nerrors and failed requests to the Cloud APIs.\n\nYou must specify a quota project because every request to a Google Cloud API is\ncounted against a quota and because quotas are enforced by project. For more\ninformation, see [How to set the quota\nproject](/docs/quotas/set-quota-project)\n.\n\nNote for gcloud CLI users: the *quota project* is sometimes referred\nto as the *billing project* . This is because the [`billing_project`\nflag](/sdk/gcloud/reference#--billing-project)\ntakes precedence over the [`billing/quota_project`\nproperty](/sdk/gcloud/reference/config/set#quota_project) in your\ngcloud CLI configuration.\n\nHow the quota project is determined\n-----------------------------------\n\nHow the quota project is determined depends on the type of API method that you\nuse: *resource-based API* or *client-based API*. In rare cases, a service might\nhave both types of API methods.\n\n### Resource-based APIs\n\nFor resource-based Cloud APIs, the project that provides quota for\nan API call is also the project that contains the resource that is being\naccessed. For example, when you create a Compute Engine instance, you must\nspecify the project for that new instance. The project then contains the newly\ncreated instance. Later, if you perform operations on the Compute Engine\ninstance, the project that contains the instance provides the quota for the\nrequest. This applies regardless of whether you use the Google Cloud CLI, REST\nAPI, or client libraries.\n\nYou cannot change the quota project used by a request to a resource-based API.\nThe request always uses the project that contains the resource that the request\nis operating on.\n\n### Client-based APIs\n\nIf an API is not a resource-based API, it's a client-based API. For example, the\nCloud Translation API is a commonly used client-based API.\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\n#### About the gcloud CLI shared project for client-based APIs\n\nIf you use the gcloud CLI to make a request to a client-based API\nwithout setting the quota project, the request might fall back on the\n*gcloud CLI shared project*, or the request might fail. The\ngcloud CLI shared project is used by all gcloud CLI\nrequests in all projects, so if many other gcloud CLI requests are\nalso using this project as their quota project, the quota for the shared project\nmight temporarily be depleted. If this happens, your request fails with an\nout-of-quota error message.\n\n#### Identify the current quota project for client-based APIs\n\nThe method for identifying the quota project depends on how your project is\nconfigured:\n\n- If an API method is configured to use a resource-based API, the client\n project uses the resource project as the quota project.\n\n- If a user project override is in place, use the\n [`gcloud [command] --log-http` command](/sdk/gcloud/reference#--log-http)\n to print a log and check the quota project that appears in the\n `x-goog-user-project` field.\n\n- If an API key was used for authentication, use the\n [`gcloud [command] --log-http` command](/sdk/gcloud/reference#--log-http)\n to print a log and check the quota project that appears in the\n `x-goog-api-key` field.\n\nFor other configurations, the quota project doesn't appear in HTTP headers.\n\nDetermine if an API is resource-based or client-based\n-----------------------------------------------------\n\nIt can be difficult to determine which type of API you're using. However,\nactivation and quotas are enforced in the same way. For example, if a service\naccount from project A calls a read method in project B, and neither project has\nthe API enabled, the `API not enabled` error message indicates which project is\nchecked for activation. The project checked for activation is the same project\nchecked for\n[rate quota](/docs/quotas/overview#types_of_quota).\n\nWhat's next\n-----------\n\n- Learn how to set the [quota\n project](/docs/quotas/set-quota-project)\n\n- Learn more about [Application Default\n Credentials](/docs/authentication/application-default-credentials)\n\n- Get more information about\n [authentication](/docs/authentication)\n\n- Understand [quotas](/docs/quotas/overview)\n\n- For gcloud CLI users:\n\n - For more information about gcloud CLI configurations, see the [`gcloud config`](/sdk/gcloud/reference/config) reference documentation\n - For more information about the `--billing_project` flag, see the [Google Cloud SDK reference](/sdk/gcloud/reference#--billing-project)"]]
