Este documento descreve como definir um projeto de quota para as APIs baseadas no cliente. Para informações sobre o que é o projeto de quota, como definir a API de quota e como o projeto de quota é determinado, consulte o artigo Acerca do projeto de quota.
Os pedidos podem falhar se fizer um pedido a uma API baseada no cliente e não for possível identificar o projeto de quota. O projeto de quota pode ser definido de várias formas e é validado através da verificação das seguintes opções. Aparecem pela seguinte ordem de precedência:
Especificado no pedido: o projeto de quota especificado no pedido. (Quando usa bibliotecas cliente, também pode usar variáveis de ambiente nas suas solicitações.)
Chave da API: se usar uma chave da API para fornecer credenciais para um pedido, o projeto associado à chave da API é usado como o projeto de quota.
Credenciais da CLI do Google Cloud: se usar a CLI gcloud para obter o token de acesso e tiver feito a autenticação na CLI gcloud com as suas credenciais de utilizador, o projeto partilhado da CLI gcloud é, por vezes, usado como o projeto de quota. No entanto, nem todas as APIs baseadas no cliente recorrem ao projeto partilhado.
Conta de serviço: se o principal para a chamada API for uma conta de serviço, inclusive por roubo de identidade, o projeto associado à conta de serviço é usado como o projeto de quota.
Federação de identidade da força de trabalho: se o principal da API for um utilizador da federação de identidade da força de trabalho, o projeto do utilizador dos conjuntos de forças de trabalho é usado como o projeto de quota.
Se nenhuma das verificações anteriores gerar um projeto de quota, o pedido falha.
Existem várias formas de definir projetos de quota. Se o projeto de quota for especificado por mais de um método, aplica-se a seguinte precedência:
- Programaticamente
- Variável de ambiente
- Credenciais usadas para autenticar o pedido
Defina o projeto de quota programaticamente
Pode definir explicitamente o projeto de quota na sua aplicação. Este método substitui todas as outras definições. O principal usado para autenticar o pedido tem de ter a autorização necessária no projeto de quota especificado.
A forma como define o projeto de quota programaticamente depende de estar a usar uma biblioteca cliente, a CLI gcloud ou um pedido da API REST.
Biblioteca cliente
Pode definir o valor para o projeto de quota através das opções do cliente quando criar o cliente. Este método funciona bem se quiser controlar o valor do projeto de quota a partir da sua aplicação, independentemente do ambiente em que está a ser executado.
Para mais informações sobre a implementação de opções de cliente, consulte a documentação da biblioteca de cliente.
CLI gcloud
Pode definir o projeto de quota para todos os comandos da CLI gcloud usando a propriedade billing/quota_project na configuração da CLI gcloud. Também pode definir o projeto de quota para um comando específico através da flag --billing-project, que tem precedência sobre a propriedade de configuração.
Para mais informações sobre as gcloudconfigurações da CLI, consulte a
gcloud config documentação.
Para mais informações acerca da flag --billing-project, consulte a
--billing-project documentação.
Pedido REST
Pode especificar o projeto de quota num pedido REST através do cabeçalho x-goog-user-project.
O principal que faz o pedido tem de ter as autorizações necessárias no projeto de quota.
Para mais informações e código de exemplo, consulte o artigo Defina o projeto de quota com um pedido REST.
Defina o projeto de quota através de uma variável de ambiente
As bibliotecas cliente para alguns idiomas suportam a definição do projeto de quota através de uma variável de ambiente. Esta abordagem pode ser útil se quiser definir o projeto de quota de forma diferente em diferentes shells ou substituir o projeto de quota associado à credencial. O principal de qualquer pedido tem de ter as autorizações necessárias no projeto de quota especificado pela variável de ambiente.
A variável de ambiente depende do idioma:
| Idioma | Variável de ambiente |
|---|---|
| C++ |
|
| C# |
|
| Ir |
|
| Java |
|
| Node.js |
|
| Python |
|
| PHP |
|
| Ruby | Não disponível |
Defina o projeto de quota através de credenciais de autenticação
Se o projeto de quota não for especificado, as bibliotecas de autenticação tentam determiná-lo a partir das credenciais usadas para o pedido. Este processo depende do tipo de credenciais que foram usadas para autenticar o pedido:
- Conta de serviço: o projeto associado à conta de serviço é usado como projeto de quota.
- Credenciais do utilizador: para um ambiente de desenvolvimento local, as Credenciais padrão da aplicação
encontram as credenciais do utilizador no ficheiro ADC local. Esse ficheiro também pode especificar um projeto de quota. Se tiver o projeto definido na configuração da CLI do Google Cloud e tiver as autorizações necessárias nesse projeto, o projeto de quota é definido por predefinição quando cria o ficheiro ADC local. Também pode definir o projeto de quota da ADC com o comando
auth application-default set-quota-project. - Chaves da API: quando usa uma chave da API para fornecer credenciais para um pedido, o projeto associado à chave da API é usado como o projeto de quota.
Autorizações necessárias para definir e usar o projeto de quota
Para receber a autorização de que
precisa para definir um projeto como o projeto de quota ou usar esse projeto de quota num pedido,
peça ao seu administrador para lhe conceder a função do IAM de
consumidor de utilização do serviço (roles/serviceusage.serviceUsageConsumer)
no projeto.
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.
Esta função predefinida contém a autorização
serviceusage.services.use
, que é necessária para
definir um projeto como o projeto de quota ou usar esse projeto de quota num pedido.
Também pode obter esta autorização com funções personalizadas ou outras funções predefinidas.
Se usar um projeto que criou como projeto de quota, tem as autorizações necessárias.
Para mais informações sobre autorizações, consulte o artigo Autorizações de quotas.
Defina o utilizador de quota
Algumas APIs também limitam o número de pedidos por utilizador, o que é diferente das quotas por projeto descritas nas secções anteriores deste documento.
Por predefinição, o sistema usa o principal autenticado. Se não existir um principal autenticado, o sistema usa o endereço IP do cliente.
Se precisar de substituir o utilizador da quota, pode definir o parâmetro quotaUser através dos parâmetros do sistema da API Cloud. Se especificar um quotaUser ou um X-Goog-Quota-User, tem de usar uma chave de API válida com restrições de endereço IP para identificar o projeto de quota. Caso contrário, o parâmetro quotaUser é ignorado.
Para saber mais sobre os parâmetros do sistema da API Cloud e as respetivas definições, consulte a tabela de definições dos parâmetros do sistema.
O que se segue?
- Acerca do projeto de quotas
- Saiba mais sobre as Credenciais padrão da aplicação
- Veja mais informações sobre a autenticação
- Compreenda as quotas