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 anteriores 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:
- De forma programática
- Variável de ambiente
- 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 API 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 sinalização --billing-project,
consulte a referência do SDK Google Cloud.
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++ |
|
| C# |
|
| Go |
|
| Java |
|
| Node.js |
|
| Python |
|
| PHP |
|
| 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 a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
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
- Sobre o projeto de cota
- Saiba mais sobre o Application Default Credentials.
- Mais informações sobre autenticação
- Entenda as cotas