Esta página descreve como criar, editar e restringir chaves da API. Para obter informações sobre como usar chaves de API para aceder às APIs Google, consulte o artigo Use chaves de API para aceder às APIs.
Introdução às chaves da API
Existem dois tipos de chaves da API: chaves da API padrão e chaves da API que foram associadas a uma conta de serviço.
Chaves da API padrão
As chaves da API padrão oferecem uma forma de associar um pedido a um projeto para fins de faturação e quotas. Quando usa uma chave da API padrão (uma chave da API que não foi associada a uma conta de serviço) para aceder a uma API, a chave da API não identifica um principal. Sem um principal, o pedido não pode usar a gestão de identidade e de acesso (IAM) para verificar se o autor da chamada tem autorização para realizar a operação pedida.
As chaves da API padrão podem ser usadas com qualquer API que aceite chaves da API, a menos que tenham sido adicionadas restrições da API à chave. Não é possível usar chaves da API padrão com serviços que não aceitam chaves da API, incluindo no modo expresso.
Chaves da API associadas a uma conta de serviço
As chaves de API associadas a uma conta de serviço fornecem a identidade e a autorização da conta de serviço a um pedido. Quando usa uma chave da API que foi associada a uma conta de serviço para aceder a uma API, o seu pedido é processado como se tivesse usado a conta de serviço associada para fazer o pedido.
A única API que suporta chaves da API associadas é a aiplatform.googleapis.com.
A associação de chaves a uma conta de serviço é impedida por uma restrição da política da organização predefinida. Para alterar esta opção, consulte o artigo Ative a associação de chaves a contas de serviço.
Componentes da chave da API
Uma chave da API tem os seguintes componentes, que lhe permitem gerir e usar a chave:
- String
- A cadeia da chave da API é uma cadeia encriptada, por exemplo,
AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Quando usa uma chave da API para aceder a uma API, usa sempre a string da chave. As chaves da API não têm um ficheiro JSON associado. - ID
- O ID da chave da API é usado pelas Google Cloud ferramentas administrativas para identificar de forma exclusiva a chave. Não é possível usar o ID da chave para aceder às APIs. Pode encontrar o ID da chave no URL da página de edição da chave na Google Cloud consola. Também pode obter o ID da chave através da CLI do Google Cloud para listar as chaves no seu projeto.
- Nome a apresentar
- O nome a apresentar é um nome descritivo opcional para a chave, que pode definir quando cria ou atualiza a chave.
- Conta de serviço associada
- As chaves de API associadas a uma conta de serviço incluem o endereço de email da conta de serviço.
Antes de começar
Conclua as seguintes tarefas para usar os exemplos nesta página.
Configure a autenticação
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
C++
Para usar os C++ exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Para mais informações, consulte Configure o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.
Java
Para usar os Java exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Para mais informações, consulte Configure o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.
Python
Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Para mais informações, consulte Configure o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.
REST
Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.
Funções necessárias
Para obter as autorizações de que precisa para gerir chaves de API, peça ao seu administrador para lhe conceder as seguintes funções da IAM no seu projeto:
-
Administrador de chaves da API (
roles/serviceusage.apiKeysAdmin) -
Restrinja uma chave da API a APIs específicas através da Google Cloud consola:
Visualizador de utilização de serviços (
roles/serviceusage.serviceUsageViewer)
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.
Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.
Ative a vinculação de chaves a contas de serviço
Antes de poder associar uma chave de API a uma conta de serviço, tem de
definir a restrição da política
organizacional constraints/iam.managed.disableServiceAccountApiKeyCreation como false. A alteração da política da organização requer um
recurso da organização
associado.
Os projetos sem uma organização não são suportados.
Para alterar a restrição de política, siga estas instruções.
Consola
Na Google Cloud consola, aceda à página Políticas de organização.
Mude para a organização, a pasta ou o projeto para o qual quer alterar as políticas.
Na caixa Filtro, introduza
Block servicee, de seguida, clique no nome do filtro Bloquear associações de chaves da API de contas de serviço.Clique em Gerir política.
Na secção Origem da política, selecione Substituir política do elemento principal.
Clique em Adicionar uma regra e defina Aplicação como Desativada.
Clique em Concluído.
Opcional: clique em Testar alterações para ver informações sobre como a política proposta pode causar violações ou interrupções da conformidade.
Clique em Definir política.
gcloud
Crie um ficheiro denominado
spec.yamlcom o seguinte conteúdo:name: SCOPE/SCOPE_ID/policies/iam.managed.disableServiceAccountApiKeyCreation spec: rules: - enforce: falseIndique os seguintes valores:
SCOPE:organizations,foldersouprojects.SCOPE_ID: consoante SCOPE, o ID da organização, da pasta ou do projeto ao qual a política de organização se aplica.
Execute o seguinte comando
gcloudpara permitir a associação de chaves de API a contas de serviço:gcloud org-policies set-policy spec.yaml \ --update-mask spec
Crie uma chave da API
Para criar uma chave da API, use uma das seguintes opções:
Consola
Na Google Cloud consola, aceda à página Credenciais:
Clique em Criar credenciais e, de seguida, selecione Chave de API no menu.
Opcional: para associar a chave da API a uma conta de serviço, selecione a caixa de verificação Autenticar chamadas da API através de uma conta de serviço e, de seguida, clique em Selecionar uma conta de serviço para selecionar a conta de serviço que quer associar à chave.
Para mais informações, consulte o artigo Chaves da API associadas a uma conta de serviço.
Adicione restrições à chave da API.
Restringir as chaves da API é uma prática recomendada. Para mais informações, consulte o artigo Aplique restrições de chaves da API.
Clique em Criar. A caixa de diálogo Chave da API criada apresenta a string da chave criada recentemente.
gcloud
Use o
gcloud services api-keys create comando
para criar uma chave da API.
Substitua DISPLAY_NAME por um nome descritivo para a chave.
gcloud services api-keys create \
--display-name=DISPLAY_NAME
Opcional: para associar a chave da API a uma conta de serviço, use gcloud beta
em vez disso, com a flag --service-account:
gcloud beta services api-keys create \
--display-name=DISPLAY_NAME \
--service-account=SERVICE_ACCOUNT_EMAIL_ADDRESS
Para mais informações, consulte o artigo Chaves da API associadas a uma conta de serviço.
C++
Para executar este exemplo, tem de instalar a biblioteca cliente API Keys.
Java
Para executar este exemplo, tem de instalar a
google-cloud-apikeys biblioteca cliente.
Python
Para executar este exemplo, tem de instalar a biblioteca cliente API Keys.
REST
Use o método
keys.create
para criar uma chave da API. Este pedido devolve uma operação de longa duração. Tem de sondar a operação para obter as informações da nova chave.
Substitua os seguintes valores:
DISPLAY_NAME: opcional. Um nome descritivo para a sua chave.PROJECT_ID: o ID ou o nome do seu projeto Google Cloud .
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d {'"displayName" : "DISPLAY_NAME"'} \ "https://apikeys.googleapis.com/v2/projects/PROJECT/locations/global/keys"
Opcional: para associar a chave da API a uma conta de serviço, use o seguinte comando:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d {'"displayName" : "DISPLAY_NAME", "serviceAccountEmail" : "SERVICE_ACCOUNT_EMAIL"'} \ "https://apikeys.googleapis.com/v2/projects/PROJECT/locations/global/keys"
Para mais informações, consulte o artigo Chaves da API associadas a uma conta de serviço.
Para mais informações sobre a criação de chaves da API através da API REST, consulte o artigo Criar uma chave da API na documentação da API Keys API.
Aplique restrições da chave da API
Por predefinição, as chaves da API não têm restrições. As chaves não restritas são inseguras porque podem ser usadas por qualquer pessoa em qualquer lugar. Para aplicações de produção, deve definir restrições de aplicações e restrições de API.
Adicione restrições de aplicações
As restrições de aplicações especificam que Websites, endereços IP ou apps podem usar uma chave da API.
Só pode aplicar um tipo de restrição de aplicação de cada vez. Escolha o tipo de restrição com base no tipo de aplicação:
| Opção | Tipo de aplicação | Notas |
|---|---|---|
| Websites | Apps Web | Especifica os Websites que podem usar a chave. |
| Endereços IP | Aplicações chamadas por servidores específicos | Especifica os servidores ou as tarefas cron que podem usar a chave. Esta é a única restrição disponível se associar a chave da API a uma conta de serviço. |
| Apps Android | Apps para Android | Especifica a aplicação Android que pode usar a chave. |
| Apps iOS | Aplicações iOS | Especifica os pacotes iOS que podem usar a chave. |
Websites
Para restringir os Websites que podem usar a sua chave da API, adicione uma ou mais restrições de referenciadores HTTP.
Pode substituir um caráter universal (*) pelo subdomínio ou pelo caminho, mas não pode inserir um caráter universal no meio de um URL. Por exemplo,
*.example.com é válido e aceita todos os sites que terminam em .example.com.
No entanto, mysubdomain*.example.com não é uma restrição válida.
Os números de porta podem ser incluídos nas restrições do referenciador HTTP. Se incluir um número de porta, apenas são correspondidos pedidos que usem essa porta. Se não especificar um número da porta, as solicitações de qualquer número da porta são correspondentes.
A tabela seguinte mostra alguns cenários de exemplo e restrições do navegador:
| Cenário | Restrições |
|---|---|
| Permita um URL específico | Adicione um URL com um caminho exato. Por exemplo:www.example.com/pathwww.example.com/path/pathAlguns navegadores implementam uma política de referenciador que envia apenas o URL de origem para pedidos de origem cruzada. Os utilizadores destes navegadores não podem usar chaves com restrições de URL específicas da página. |
| Permitir qualquer URL no seu site | Tem de definir dois URLs na lista allowedReferers.
|
| Permitir qualquer URL num único subdomínio ou domínio simples |
Tem de definir dois URLs na lista
|
Para restringir a sua chave da API a Websites específicos, use uma das seguintes opções:
Consola
Na Google Cloud consola, aceda à página Credenciais:
Clique no nome da chave de API que quer restringir.
Na secção Restrições de aplicações, selecione Referenciadores HTTP.
Para cada restrição que quer adicionar, clique em Adicionar um item, introduza a restrição e clique em Concluído.
Clique em Guardar para guardar as alterações e voltar à lista de chaves da API.
gcloud
Obtenha o ID da chave que quer restringir.
O ID não é igual ao nome a apresentar nem à string da chave. Pode obter o ID através do comando
gcloud services api-keys listpara listar as chaves no seu projeto.Use o comando
gcloud services api-keys updatepara adicionar restrições de referenciadores HTTP a uma chave da API.Substitua os seguintes valores:
KEY_ID: o ID da chave que quer restringir.ALLOWED_REFERRER_1: A sua restrição de referenciador HTTP.Pode adicionar as restrições necessárias. Use vírgulas para separar as restrições. Tem de fornecer todas as restrições de referenciadores com o comando update. As restrições de referenciadores fornecidas substituem quaisquer restrições de referenciadores existentes na chave.
gcloud services api-keys update KEY_ID \ --allowed-referrers="ALLOWED_REFERRER_1"
Java
Para executar este exemplo, tem de instalar a
google-cloud-apikeys biblioteca cliente.
Python
Para executar este exemplo, tem de instalar a biblioteca cliente API Keys.
REST
Obtenha o ID da chave que quer restringir.
O ID não é igual ao nome a apresentar nem à string da chave. Pode obter o ID através do método keys.list. O ID está listado no campo
uidda resposta.Substitua
PROJECT_IDpelo ID ou nome do seu Google Cloud projeto.curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/"
Use o método keys.patch para adicionar restrições de referenciadores HTTP à chave da API.
Este pedido devolve uma operação de execução longa. Tem de verificar a operação para saber quando esta é concluída e obter o respetivo estado.
Substitua os seguintes valores:
ALLOWED_REFERRER_1: A sua restrição de referenciador HTTP.Pode adicionar as restrições necessárias. Use vírgulas para separar as restrições. Tem de fornecer todas as restrições de referenciadores com o pedido. As restrições de referenciadores fornecidas substituem quaisquer restrições de referenciadores existentes na chave.
PROJECT_ID: o ID ou o nome do seu projeto Google Cloud .KEY_ID: o ID da chave que quer restringir.
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data '{ "restrictions" : { "browserKeyRestrictions": { "allowedReferrers": ["ALLOWED_REFERRER_1"] } } }' \ "https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"
Para mais informações sobre como adicionar restrições de referenciadores HTTP a uma chave através da API REST, consulte o artigo Adicionar restrições de navegador na documentação da API API Keys.
Endereços IP
Pode especificar os endereços IP externos dos autores da chamada (como servidores Web ou tarefas cron) que têm autorização para usar as suas chaves da API. Pode especificar endereços IP nos seguintes formatos:
IPv4 (
198.51.100.1)IPv6 (
2001:db8::1)Uma sub-rede que usa a notação CIDR (
198.51.100.0/24,2001:db8::/64)
Os endereços IP internos e localhost não são suportados.
Para restringir a sua chave da API a endereços IP externos específicos, use uma das seguintes opções:
Consola
Na Google Cloud consola, aceda à página Credenciais:
Clique no nome da chave de API que quer restringir.
Na secção Restrições de aplicações, selecione Endereços IP.
Para cada endereço IP que quer adicionar, clique em Adicionar um item, introduza o endereço e clique em Concluído.
Clique em Guardar para guardar as alterações e voltar à lista de chaves da API.
gcloud
Obtenha o ID da chave que quer restringir.
O ID não é igual ao nome a apresentar nem à string da chave. Pode obter o ID através do comando
gcloud services api-keys listpara listar as chaves no seu projeto.Use o comando
gcloud services api-keys updatepara adicionar restrições de servidor (endereço IP) a uma chave da API.Substitua os seguintes valores:
KEY_ID: o ID da chave que quer restringir.ALLOWED_IP_ADDR_1: o seu endereço IP permitido.Pode adicionar todos os endereços IP necessários. Use vírgulas para separar os endereços.
gcloud services api-keys update KEY_ID \ --allowed-ips="ALLOWED_IP_ADDR_1"
Java
Para executar este exemplo, tem de instalar a
google-cloud-apikeys biblioteca cliente.