Como usar chaves de API

Este tópico mostra aos desenvolvedores de aplicativos como usar chaves de API com as APIs do Google Cloud. Uma chave de API é uma string criptografada simples que identifica um aplicativo sem principal. Elas são úteis para acessar dados públicos de forma anônima e são usadas na associação de solicitações de API ao seu projeto para cota e faturamento.

Para saber mais sobre a autenticação nas APIs do Google Cloud e determinar a melhor estratégia de autenticação para cenários comuns, consulte Visão geral da autenticação. Para saber mais sobre como usar chaves de API para SDKs e APIs da plataforma do Google Maps, consulte a documentação da Plataforma Google Maps.

Como gerenciar chaves de API

Recomendamos que você use o Console do Cloud para gerenciar chaves de API. Navegue até a página APIs e serviços → Credenciais, no Console do Cloud. Suas chaves de API são exibidas na seção Chaves de API. Nessa página, você pode criar chaves de API, definir restrições de chave de API, alternar strings de chave de API e realizar outras ações.

Criar chave de API

Para criar uma chave de API em um projeto, o usuário precisa receber o papel básico de Editor (roles/editor). Consulte "Papéis básicos" para mais informações.

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 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 chaves de API nos seus aplicativos, garanta que elas sejam mantidas em segurança durante o armazenamento e a transmissão. A exposição pública das credenciais resulta no comprometimento da 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 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 aplicar restrições de chave de API

As chaves de API são irrestritas por padrão. As chaves irrestritas não são seguras porque podem ser usadas por qualquer pessoa e de qualquer lugar. Para aplicativos de produção, defina as restrições de aplicativos e as restrições de API.

Para adicionar restrições de chave de API:

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

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

Como adicionar restrições de aplicativos

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 a seção Como adicionar restrições HTTP abaixo 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

As chaves de API usadas por aplicativos da Web devem ter 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ê deverá adicionar restrições separadamente.

Como adicionar restrições de API

Essas restrições especificam quais APIs podem ser chamadas com a chave de API. Todas as chaves de API usadas pelos aplicativos de produção devem ter restrições de 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.

A seguir