Como usar chaves de API

Neste guia, você verá como criar chaves de API e como configurar restrições de chave de API para aplicativos do Google Cloud. Para saber mais sobre a autenticação em uma API do Google Cloud, consulte Visão geral da autenticação. Para informações sobre as chaves de API das APIs e dos SDKs do Google Maps Platform, consulte a documentação do Google Maps.

As chaves de API são strings criptografadas simples, utilizadas quando você chama determinadas APIs que não precisam acessar dados particulares de usuários. Essas chaves são úteis em clientes como aplicativos móveis e navegadores que não têm um servidor de back-end. A chave de API é usada para rastrear solicitações de APIs associadas ao projeto para cota e faturamento.

As chaves de API têm limitações importantes:

Por isso, recomendamos usar o fluxo de autenticação padrão. No entanto, há casos limitados em que as chaves de API são mais apropriadas. Por exemplo, se você estiver desenvolvendo um aplicativo para dispositivos móveis que precise usar a API Cloud Translation, mas não precisa de um servidor de back-end, as chaves de API são a maneira mais simples de autenticar essa API. Na maioria dos casos, é recomendável que o aplicativo se comunique com um servidor de back-end que faça a autenticação e a chamada dos serviços do Google Cloud.

Criar chave de API

Para você fazer isso, sua conta precisa receber o papel primário Editor (roles/editor) no projeto atual. Para mais informações, consulte Papéis primários.

Para criar uma chave de API, siga estas etapas:

  1. Acesse o painel APIs e serviços→Credenciais no Console do Cloud.

  2. Clique em Criar credenciais e, em seguida, selecione a chave de API no menu suspenso.

  3. A chave recém-criada será exibida na caixa de diálogo Chave de API criada.

Copie sua chave e a mantenha em segurança. A menos que você esteja usando uma chave de teste que queira excluir mais tarde, adicione restrições de aplicativo e chave de API.

Como usar uma chave de API

Transmita a chave de API em uma chamada da API REST como um parâmetro de consulta com o formato a seguir. Substitua API_KEY pela sua chave de API:

key=API_KEY

Por exemplo, para transmitir uma chave de API de uma solicitação da API Cloud Natural Language a documents.analyzeEntities:

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

Como proteger uma chave de API

Ao usar as chaves de API nos aplicativos, tome cuidado para mantê-las em segurança. A exposição das credenciais resulta no comprometimento da sua conta, o que pode gerar cobranças inesperadas. Para manter as chaves de API em segurança, siga estas práticas recomendadas:

  • Não incorpore as chaves de API diretamente no código, elas podem ser expostas acidentalmente. Por exemplo, caso você se esqueça de remover as chaves do código compartilhado. Em vez de incorporá-las nos aplicativos, armazene essas chaves em variáveis de ambiente ou em arquivos fora da árvore de origem do seu aplicativo.

  • Não armazene as chaves de API em arquivos dentro da árvore de origem do aplicativo. Se essas chaves forem mantidas em arquivos, mantenha esses arquivos fora da árvore de origem do aplicativo, para garantir que as chaves não fiquem no sistema de controle do código-fonte. Isso é especialmente importante se você usa um sistema de gerenciamento de código-fonte público, como o GitHub.

  • Configure as restrições de aplicativo e chave de API. Ao adicionar restrições, é possível reduzir o impacto de uma chave de API comprometida.

  • Exclua chaves de API desnecessárias para minimizar a exposição a ataques.

  • Gere novamente as chaves de API com frequência. Para isso, na página "Credenciais", clique em Gerar chave novamente para cada uma delas. Em seguida, atualize seus aplicativos para que as chaves recém-geradas sejam usadas. As chaves antigas continuarão a funcionar 24 horas após você gerar as chaves de substituição.

  • Revise o código antes de liberá-lo publicamente. O código não deve conter chaves de API ou outras informações confidenciais ao ser disponibilizado publicamente.

Como adicionar restrições às chaves de API

Por padrão, uma chave de API não tem restrições. As chaves sem restrições não são seguras porque podem ser visualizadas publicamente, como em um navegador, ou acessadas no dispositivo em que elas residem.

Para aplicativos de produção, defina restrições do aplicativo e da API.

Para adicionar restrições de chave de API, siga estas instruções:

  1. Acesse o painel APIs e serviços→Credenciais no Console do Cloud.

  2. Selecione o nome de uma chave de API atual.

Restrições do aplicativo

As restrições de aplicativo especificam quais sites, endereços IP ou apps podem usar uma chave de API. Adicione restrições de aplicativo com base no tipo de aplicativo. É possível definir apenas um tipo de restrição por chave de API.

Escolha o tipo de restrição com base nas necessidades do seu aplicativo.

  • Use Nenhuma apenas para fins de teste.

  • Use referenciadores HTTP para clientes de API executados em um navegador da Web. Dessa maneira, somente as páginas especificadas podem chamar a API. Esses tipos de aplicativos expõem as chaves de API publicamente. Portanto, recomendamos usar uma conta de serviço. Consulte Como adicionar restrições HTTP para ver exemplos.

  • Use endereços IP para limitar o acesso a chaves de API a determinados endereços IP.

  • Use apps Android para aplicativos Android. Essa opção obriga a adicionar o nome do pacote e a impressão digital do certificado de assinatura SHA-1.

  • Use apps iOS para aplicativos iOS. Nessa opção, é preciso adicionar pelo menos um identificador do pacote iOS para restringir chamadas de API a pacotes do iOS específicos.

Como adicionar restrições HTTP

Para fazer isso, siga estas etapas:

  • Selecione Referenciadores HTTP (sites) na seção Restrições do aplicativo.

  • Insira pelo menos uma restrição na seção Restrições de sites.

  • Se o domínio for compatível com HTTP e HTTPS, as restrições precisarão ser adicionadas separadamente.

  • Também é possível usar caracteres curinga (*) para o subdomínio e/ou o caminho.

A tabela a seguir mostra cenários e restrições de exemplo, do mais restritivo ao menos restritivo. Recomendamos usar o exemplo mais restritivo adequado ao caso de uso.

Cenário Restrições
Permitir um URL específico.

Adicione uma única restrição a um caminho exato. Exemplo:

  • https://www.example.com/path
  • http://www.example.com/path/path
Permitir qualquer URL em um único subdomínio ou domínio sem "www".

Defina pelo menos duas restrições para permitir um domínio inteiro.

  1. Defina uma restrição para o domínio sem a barra no final. Por exemplo:
    • https://www.example.com
    • http://sub.example.com
    • http://example.com
  2. Defina uma segunda restrição para o domínio que inclua um caractere curinga no caminho. Por exemplo:
    • https://www.example.com/*
    • http://sub.example.com/*
    • http://example.com/*
  3. Se o domínio permitir HTTP e HTTPS, você precisará adicionar mais restrições separadamente.
Permitir todos os URLs de subdomínio em um único domínio.

Defina pelo menos duas restrições.

  1. Defina uma restrição para o domínio, com um caractere curinga para o subdomínio e sem a barra final. Por exemplo:
    • https://*.example.com
  2. Defina uma segunda restrição para o domínio que inclua um caractere curinga no caminho, como:
    • https://*.example.com/*
  3. Se o domínio permitir HTTP e HTTPS, você precisará adicionar mais restrições separadamente.

Restrições da API

As restrições da API especificam quais APIs podem ser chamadas com a chave de API. Todas as chaves de API usadas em aplicativos de produção devem usar restrições da API.

Para definir restrições da API, siga estas etapas:

  1. Clique em Restringir chave na seção Restrições da API.

  2. Selecione no menu suspenso todos os nomes de API que a chave precisa chamar.

  3. Clique no botão Salvar.

Como ver chaves de API atuais

Use o Console do Cloud para fazer isso. Acesse o painel APIs e serviços→Credenciais no Console do Cloud e, depois isso, confira as chaves abaixo do cabeçalho Chaves de API.

A seguir