Como usar chaves de API

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

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 para dispositivos móveis e para navegador 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 Google Cloud Translation, mas que não necessite de um servidor de back-end, as chaves de API serão a maneira mais simples de autenticar essa API. Na maioria dos casos, recomendamos que seu aplicativo se comunique com um servidor de back-end que cuide da autenticação e chame os serviços do Google Cloud Platform.

Como criar uma chave de API

Para criar uma chave de API, 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 para uma chamada da API REST como um parâmetro de consulta com o seguinte formato. 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, se você se esquecer de remover as chaves do código compartilhado. Em vez de incorporá-las nos aplicativos, armazene-as 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 armazenadas em arquivos, mantenha-os fora da árvore de origem do aplicativo, para garantir que elas 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 as chaves de API novamente 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. Verifique se o código não contém chaves de API ou outras informações particulares ao ser disponibilizado para o público.

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 de aplicativo

As restrições de aplicativo especificam quais sites, endereços IP ou apps podem usar uma chave de API. Adicione restrições 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 de HTTP para exemplos.

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

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

  • Use apps para iOS para aplicativos desse sistema operacional. Essa opção obriga a 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 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 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

Essas restrições especificam quais APIs podem ser chamadas com a chave de API. Todas as chaves de API usadas em aplicativos de produção precisam 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. Depois de acessar o painel APIs e serviços→Credenciais no Console do Cloud, as chaves de API atuais são exibidas abaixo do cabeçalho Chaves de API.

A seguir