Definir o projeto de cota

Nesta página, descrevemos como definir um projeto de cota para suas APIs baseadas em cliente. Para mais informações sobre o que é o projeto de cota, como definir a API de cota e como ele é determinado, consulte Sobre o projeto de cota.

Ao fazer uma solicitação a uma API baseada em cliente, se não for possível identificar um projeto de cota, a solicitação falhará.

O projeto de cota pode ser definido de várias maneiras e será verificado nas opções a seguir. A ordem listada é a da precedência.

  • O projeto de cota definido no ambiente ou na solicitação.
  • Se você usar uma chave de API para fornecer credenciais de uma solicitação, o projeto associado a ela será usado como o projeto de cota.
  • Se você usa a CLI do Google Cloud para receber o token de acesso e fez a autenticação na CLI gcloud com suas credenciais de usuário, o projeto compartilhado da CLI gcloud às vezes é usado como o projeto de cota. Nem todas as APIs baseadas em cliente recorrem ao projeto compartilhado.
  • Se o principal da chamada de API for uma conta de serviço, inclusive por representação, o projeto associado à conta de serviço será usado como o projeto de cota.
  • Se o principal da API for um usuário da federação de identidade de colaboradores, o projeto de usuário dos pools de força de trabalho será usado como o projeto de cota.

Se nenhuma das verificações acima resultar em um projeto de cota, a solicitação falhará.

Há várias maneiras de definir projetos de cota. Se o projeto de cota for especificado por mais de um método, a seguinte precedência será aplicada:

  1. De forma programática
  2. Variável de ambiente
  3. Credenciais usadas para autenticar a solicitação

Definir o projeto de cota de maneira programática

É possível definir explicitamente o projeto de cota no aplicativo. Esse método substitui todas as outras definições. O principal usado para autenticar a solicitação precisa ter a permissão necessária no projeto de cota especificado.

A definição programática do projeto de cota depende do uso de uma biblioteca de cliente, da CLI gcloud ou de uma solicitação REST.

Biblioteca de cliente

É possível definir o valor do projeto de cota usando as opções do cliente na criação dele. Esse método funciona bem se você quiser controlar o valor do projeto de cota pelo aplicativo, independentemente do ambiente em que ele seja executado.

Para mais informações sobre como implementar opções do cliente, consulte a documentação da sua biblioteca de cliente.

CLI da gcloud

É possível definir o projeto de cota para todos os comandos da CLI gcloud usando a propriedade billing/quota_project na configuração da CLI gcloud. Também é possível definir o projeto de cota para um comando específico usando a flag --billing-project, que tem precedência sobre a propriedade de configuração.

Para mais informações sobre as configurações da CLI gcloud, consulte a página de referência da gcloud config. Para mais informações sobre a flag --billing-project, consulte a referência de flags globais.

Solicitação REST

É possível especificar o projeto de cota em uma solicitação REST usando o cabeçalho x-goog-user-project. O principal que fez a solicitação precisa ter as permissões necessárias no projeto de cota.

Para mais informações e exemplos de código, consulte Definir o projeto de cota com uma solicitação REST.

Definir o projeto de cota usando uma variável de ambiente

As bibliotecas de cliente de algumas linguagens permitem configurar o projeto de cota com uma variável de ambiente. Essa abordagem poderá ser útil se você quiser definir o projeto de cota de maneira diferente em diferentes shells ou modificar o projeto de cota associado à credencial. O principal de qualquer solicitação precisa ter as permissões necessárias no projeto de cota especificado pela variável de ambiente.

A variável de ambiente depende do idioma:

Idioma Variável de ambiente
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 Indisponível

Definir o projeto de cota usando credenciais de autenticação

Se o projeto de cota não for especificado, as bibliotecas de autenticação vão tentar determinar a partir das credenciais usadas para a solicitação. Esse processo depende do tipo de credenciais usadas para autenticar a solicitação:

  • Conta de serviço: o projeto associado à conta de serviço é usado como o projeto de cota.
  • Credenciais do usuário: para um ambiente de desenvolvimento local, o Application Default Credentials encontra suas credenciais de usuário no arquivo ADC local. Esse arquivo também pode especificar um projeto de cota. Se você tiver o projeto definido na configuração da CLI do Google Cloud e tiver as permissões necessárias nesse projeto, ele será definido por padrão quando o arquivo ADC local for criado. Também é possível definir o projeto de cota do ADC usando o comando auth application-default set-quota-project.
  • Chaves de API: quando você usa uma chave de API para fornecer credenciais a uma solicitação, o projeto associado a ela é utilizado como projeto de cota.

Permissão necessária para definir e usar o projeto de cota

Para receber a permissão necessária para definir um projeto como o de cota ou para usar esse projeto em uma solicitação, peça ao administrador para conceder a você o Papel do IAM de Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém a permissão serviceusage.services.use, que é necessária para definir um projeto como o de cota ou usar esse projeto em uma solicitação.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Se você usar um projeto criado como seu projeto de cota, terá as permissões necessárias.

Para mais informações sobre permissões, consulte Permissões de cota.

Definir o usuário da cota

Algumas APIs também limitam o número de solicitações por usuário, o que é diferente das cotas por projeto descritas nas seções anteriores desta página.

Por padrão, o sistema usa o principal autenticado. Se não houver um principal autenticado, o sistema usará o endereço IP do cliente.

Se você precisar substituir o usuário da cota, defina o parâmetro quotaUser por meio dos parâmetros do sistema da API do Cloud. Se você especificar quotaUser ou X-Goog-Quota-User, use uma chave de API válida com restrições de endereço IP para identificar o projeto de cota. Caso contrário, o parâmetro quotaUser será ignorado.

Para saber mais sobre os parâmetros do sistema da API do Cloud e as definições deles, consulte a tabela de definições de parâmetros do sistema.

A seguir