할당량 프로젝트 설정

이 페이지에서는 클라이언트 기반 API의 할당량 프로젝트를 설정하는 방법을 설명합니다. 할당량 프로젝트 정의, 할당량 API 설정 방법, 할당량 프로젝트 결정 방법에 대한 자세한 내용은 할당량 프로젝트 정보를 참조하세요.

클라이언트 기반 API에 대한 요청을 수행할 때 할당량 프로젝트를 식별할 수 없으면 요청이 실패합니다.

할당량 프로젝트는 여러 방법으로 설정할 수 있으며, 프로젝트는 다음 옵션을 확인하여 인증됩니다. 나열된 순서는 우선순위입니다.

  • 환경 또는 요청에 설정된 할당량 프로젝트
  • API 키를 사용하여 요청의 사용자 인증 정보를 제공하는 경우 API 키와 연결된 프로젝트가 할당량 프로젝트로 사용됩니다.
  • Google Cloud CLI를 사용하여 액세스 토큰을 가져오고 사용자 인증 정보로 gcloud CLI에 인증한 경우 gcloud CLI 공유 프로젝트가 할당량 프로젝트로 사용되는 경우도 있습니다. 모든 클라이언트 기반 API가 공유 프로젝트를 사용하는 것은 아닙니다.
  • 가장에 의한 경우를 포함하여 API 호출의 주 구성원이 서비스 계정인 경우 해당 서비스 계정과 연결된 프로젝트가 할당량 프로젝트로 사용됩니다.
  • API의 주 구성원이 직원 ID 제휴 사용자인 경우 직원 풀 사용자 프로젝트가 할당량 프로젝트로 사용됩니다.

앞의 검사 중 어느 것도 할당량 프로젝트를 생성하지 않으면 요청이 실패합니다.

할당량 프로젝트를 설정하는 방법에는 여러 가지가 있습니다. 할당량 프로젝트가 둘 이상의 메서드로 지정된 경우 다음 우선순위가 적용됩니다.

  1. 프로그래매틱 방식
  2. 환경 변수
  3. 요청 인증에 사용되는 사용자 인증 정보

할당량 프로젝트를 프로그래매틱 방식으로 설정

애플리케이션에서 할당량 프로젝트를 명시적으로 설정할 수 있습니다. 이 메서드는 다른 모든 정의보다 우선 적용됩니다. 요청을 인증하는 데 사용되는 주 구성원은 지정된 할당량 프로젝트에 대한 필수 권한이 있어야 합니다.

프로그래매틱 방식으로 할당량 프로젝트를 설정하는 방법은 클라이언트 라이브러리, gcloud CLI, REST API 요청을 사용하는지 여부에 따라 달라집니다.

클라이언트 라이브러리

클라이언트를 만들 때 클라이언트 옵션을 사용하여 할당량 프로젝트 값을 설정할 수 있습니다. 이 방법은 실행 환경에 관계없이 애플리케이션에서 할당량 프로젝트 값을 제어하려는 경우에 적합합니다.

클라이언트 옵션 구현에 대한 자세한 내용은 클라이언트 라이브러리 문서를 참조하세요.

gcloud CLI

gcloud CLI 구성에서 billing/quota_project 속성을 사용하여 모든 gcloud CLI 명령어에 대한 할당량 프로젝트를 설정할 수 있습니다. 또한 구성 속성보다 우선하는 --billing-project 플래그를 사용하여 특정 명령어에 할당량 프로젝트를 설정할 수 있습니다.

gcloud CLI 구성에 대한 자세한 내용은 gcloud 구성 참조 페이지를 확인하세요. --billing-project 플래그에 관한 자세한 내용은 Google Cloud SDK 참조를 참고하세요.

REST 요청

x-goog-user-project 헤더를 사용하여 REST 요청에서 할당량 프로젝트를 지정할 수 있습니다. 요청을 수행하는 주 구성원은 할당량 프로젝트에 필요한 권한이 있어야 합니다.

자세한 내용 및 샘플 코드는 REST 요청으로 할당량 프로젝트 설정을 참조하세요.

환경 변수를 사용하여 할당량 프로젝트 설정

일부 언어의 클라이언트 라이브러리는 환경 변수를 사용한 할당량 프로젝트 설정을 지원합니다. 이 접근 방식은 서로 다른 셸에서 할당량 프로젝트를 다르게 설정하거나 사용자 인증 정보와 연결된 할당량 프로젝트를 재정의하려는 경우에 유용할 수 있습니다. 모든 요청의 주 구성원은 환경 변수로 지정된 할당량 프로젝트에 필요한 권한이 있어야 합니다.

환경 변수는 언어에 따라 다릅니다.

언어 환경 변수
C++

GOOGLE_CLOUD_CPP_USER_PROJECT

C#

GOOGLE_CLOUD_QUOTA_PROJECT

Go

GOOGLE_CLOUD_QUOTA_PROJECT

자바

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 키와 연결된 프로젝트가 할당량 프로젝트로 사용됩니다.

할당량 프로젝트 설정 및 사용에 필요한 권한

프로젝트를 할당량 프로젝트로 설정하거나 요청에 이 할당량 프로젝트를 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 프로젝트를 할당량 프로젝트로 설정하거나 요청에 해당 할당량 프로젝트를 사용하는 데 필요한 serviceusage.services.use 권한이 포함되어 있습니다.

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

만든 프로젝트를 할당량 프로젝트로 사용하는 경우 필요한 권한을 갖습니다.

권한에 관한 자세한 내용은 할당량 권한을 참고하세요.

할당량 사용자 설정

일부 API는 사용자당 요청 수를 제한하기도 합니다. 이는 이 페이지의 이전 섹션에 설명된 프로젝트별 할당량과 다릅니다.

기본적으로 시스템은 인증된 주 구성원을 사용합니다. 인증된 주 구성원이 없으면 시스템은 클라이언트 IP 주소를 사용합니다.

할당량 사용자를 재정의해야 하는 경우 Cloud API 시스템 매개변수를 통해 quotaUser 매개변수를 설정할 수 있습니다. quotaUser 또는 X-Goog-Quota-User를 지정하는 경우 IP 주소 제한이 있는 유효한 API 키를 사용하여 할당량 프로젝트를 식별해야 합니다. 그렇지 않으면 quotaUser 매개변수가 무시됩니다.

Cloud API 시스템 매개변수 및 정의에 관한 자세한 내용은 시스템 매개변수 정의 표를 참고하세요.

다음 단계