Práticas recomendadas da chave de API

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

As chaves de API são obrigatórias para apps e projetos que usam os SDKs e as APIs da Plataforma Google Maps. Este documento identifica o uso pretendido das chaves de API, como protegê-las da mesma forma que outras credenciais e quais restrições são apropriadas para os projetos.

O que são chaves de API?

As chaves de API são credenciais específicas do projeto que atendem a dois propósitos:

  • Identificação do projeto.
    Identificar o app ou projeto que está fazendo uma chamada para a API ou o SDK.
  • Autorização do projeto.
    Verificar se o app recebeu acesso para chamar a API ou o SDK e conta com API ou SDK ativado no projeto.

Quando uma chave de API é criada, ela é associada a um projeto. Ao identificar o projeto da chamada, uma chave de API permite que as informações de uso sejam associadas a esse projeto e ajuda a garantir que as chamadas de outros projetos sejam rejeitadas.

Proteger chaves de API

Recomendamos proteger as chaves de API no seu aplicativo para todos os produtos da Plataforma Google Maps que ele usa. Para isso, coloque restrições e implemente as práticas recomendadas apropriadas para as APIs da Plataforma Google Maps no aplicativo. A exposição pública de credenciais não seguras pode resultar em uso não intencional, o que talvez gere cobranças inesperadas na sua conta.

As práticas a seguir descrevem estratégias para ajudar a proteger as chaves de API. As práticas recomendadas para um produto específico da Plataforma Google Maps, como a API Maps JavaScript, estão listadas na seção Restrições e práticas recomendadas da chave de API.

  • Restrinja suas chaves de API. Para proteger melhor sua chave, restrinja-a a determinados endereços IP, URLs referenciadores ou apps para dispositivos móveis e APIs específicas, porque isso reduz significativamente o impacto em caso de comprometimento da chave.

    Para especificar restrições de aplicativo e API de uma chave no console, abra a página "Credenciais" e, em seguida, crie uma nova chave de API com as configurações desejadas ou edite as configurações de uma chave existente. Consulte a seção Restringir chaves de API para ver todos os detalhes.

  • Use chaves de API independentes para apps diferentes. Isso limita o escopo de cada chave. Se uma chave de API for comprometida, será possível excluir e revogar essa chave sem precisar atualizar suas outras chaves.
  • Exclua chaves de API desnecessárias.

    Para excluir uma chave de API, faça o seguinte:

    1. Acesse o painel de credenciais.
    2. Selecione a chave de API que você quer excluir.
    3. Clique no botão Excluir, na parte superior da página.
    4. Quando o pop-up Excluir credencial for exibido, clique em EXCLUIR.
  • Tenha cuidado ao gerar novamente chaves de API. Se o tempo necessário para migrar os aplicativos da chave de API antiga para a nova ultrapassar 24 horas, as instâncias que não forem atualizadas serão interrompidas, já que fazem referência à chave antiga (que é destruída 24 horas após a nova emissão).

    Quando você gera novamente uma chave de API, o seguinte acontece:

    • Uma nova chave resulta do processo de regeneração.
    • A nova chave recebe todas as restrições da chave antiga.
    • A janela de 24 horas começa, marcando o período até que a chave antiga seja destruída.
  • Monitore o uso da API em busca de anomalias. Se você observar uso não autorizado, alterne suas chaves e notifique o Google.

    Antes de alternar uma chave, mantenha as restrições associadas a ela, fazendo uma cópia em um arquivo.

  • Nos apps que usam as APIs Maps Web Service ou APIs Static Web, utilize os seguintes métodos para proteger seus apps e chaves de API:

  • Nos apps para dispositivos móveis que usam APIs Web Service ou APIs Static Web, utilize uma ou mais das seguintes técnicas para proteger suas chaves de API ou chaves secretas de assinatura:

Restringir chaves de API

As chaves de API são credenciais que devem ser gerenciadas com cuidado. Siga as recomendações abaixo para manter as chaves seguras e garantir restrições para reduzir o impacto caso elas sejam comprometidas.

Para restringir uma chave de API, você pode especificar uma restrição de aplicativo ou uma ou mais restrições de API.

As restrições de aplicativo limitam o uso das chaves de API a sites específicos (endereço IP e site) ou plataformas específicas (Android e iOS). É possível selecionar no máximo uma restrição dessa categoria (consulte APIs da Plataforma Google Maps por plataforma).

As restrições da API limitam o uso das chaves a um ou mais SDKs ou APIs da Plataforma Google Maps. Os pedidos para usar APIs ou SDKs associados a uma chave de API serão processados, enquanto os pedidos de APIs ou SDKs que não estão associados a uma chave falharão. Para uma chave de API, você pode especificar quantas restrições forem necessárias. Verifique se as APIs ou os SDKs associados a uma chave são compatíveis com a restrição de aplicativo definida para ela.

Definir uma restrição de aplicativo para uma chave de API

  1. Acesse o painel de credenciais.
  2. Selecione a chave de API em que você quer definir uma restrição. A página de propriedades será exibida.
  3. Em Restrições de chave, selecione Restrições de aplicativo.
    Selecione um dos tipos de restrição e insira as informações solicitadas após a lista de restrições.
    Tipo de restrição Descrição
    Referenciadores HTTP

    Aceita solicitações da lista de sites que você disponibilizar.

    Abaixo dos tipos, especifique um ou mais sites referenciadores. É possível usar caracteres curinga para nomear sites semelhantes. Por exemplo, *.google.com aceita todos os sites que terminam em google.com, como https://developers.google.com.

    Endereços IP

    Aceita as solicitações da lista de endereços IP do servidor da Web que você disponibilizar.

    Abaixo dos tipos, especifique um endereço IPv4 ou IPv6 ou uma sub-rede usando a notação CIDR (por exemplo, 192.168.0.0/22). Se você precisar inserir outra entrada, uma nova caixa aparecerá depois que a ação anterior for concluída.

    Apps Android

    Insere o nome do seu pacote e a impressão digital do certificado de assinatura SHA-1 para restringir o uso ao seu app Android.

    Abaixo dos tipos, adicione a impressão digital do certificado de assinatura SHA-1 e o nome do pacote Android retirado do arquivo AndroidManifest.xml.

    Apps iOS

    Aceita solicitações do app iOS com o identificador do pacote que você disponibilizar.

    Abaixo dos tipos, selecione o identificador iOS correto na lista.

  4. Clique em Salvar.
    A restrição se torna parte da definição de chave de API após essa etapa. Se você não enviar os detalhes corretos ou não clicar em "Salvar", a chave de API não será restringida. Para mais informações, consulte o guia Acessar uma chave de API da API ou do SDK específico em que você tem interesse.

Definir uma restrição de API em uma chave de API

  1. Acesse o painel de credenciais.
  2. Selecione a chave de API que você quer restringir.
    A página Restringir e renomear a chave de API é exibida.
  3. Em Restrições de API:
    • Clique em Restringir chave.
    • Clique na lista suspensa Selecionar APIs e escolha as APIs ou os SDKs que seu aplicativo deve acessar usando a chave de API. Se uma API ou um SDK não aparecer na lista, será preciso ativá-lo.
  4. Clique em Salvar.
    A restrição se torna parte da definição de chave de API após essa etapa. Se você não enviar os detalhes corretos ou não clicar em "Salvar", a chave de API não será restringida. Para mais informações, consulte o guia Acessar uma chave de API da API ou do SDK específico em que você tem interesse.

Restrições e práticas recomendadas para chaves de API

As tabelas a seguir mostram as restrições de chave de API e as práticas recomendadas adequadas para cada API, SDK ou serviço da Plataforma Google Maps.

Sites com APIs Maps JavaScript, Embed ou Static

API/SDK/serviço Restrição de aplicativo(1) Restrição de API(1) Práticas recomendadas
API Maps JavaScript(2) Restrição de referenciador de HTTP API Maps JavaScript
API Directions Service, API Maps JavaScript Restrição de referenciador de HTTP API Directions, API Maps JavaScript
API Distance Matrix Service, Maps JavaScript Restrição de referenciador de HTTP API Distance Matrix, API Maps JavaScript
API Elevation Service, Maps JavaScript Restrição de referenciador de HTTP API Elevation, API Maps JavaScript
API Geocoding Service, Maps JavaScript Restrição de referenciador de HTTP API Geocoding, API Maps JavaScript
API Places Library, Maps JavaScript Restrição de referenciador de HTTP API Places, API Maps JavaScript
API Maps Embed Restrição de referenciador de HTTP API Maps Embed
API Maps Static Restrição de referenciador de HTTP API Maps Static
API Street View Static Restrição de referenciador de HTTP API Street View Static

Apps e servidores que usam serviços da Web

API/SDK/serviço Restrição de aplicativo(1) Restrição de API(1) Práticas recomendadas
API Directions Restrição de endereço IP(4) API Directions
API Distance Matrix Restrição de endereço IP(4) API Distance Matrix
API Elevation Restrição de endereço IP(4) API Elevation
API Geocoding Restrição de endereço IP(4) API Geocoding
API Geolocation Restrição de endereço IP(4) API Geolocation
API Places(5) Restrição de endereço IP(4) API Places
API Roads Restrição de endereço IP(4) API Roads
API Time Zone Restrição de endereço IP(4) API Time Zone

Apps Android

API/SDK/serviço Restrição de aplicativo(1) Restrição de API(1) Práticas recomendadas
SDK do Maps para Android Restrição para Android SDK do Maps para Android
SDK do Places para Android Restrição para Android API Places

Apps iOS

API/SDK/serviço Restrição de aplicativo(1) Restrição de API(1) Práticas recomendadas
SDK do Maps para iOS Restrição para iOS SDK do Maps para iOS
SDK do Places para iOS Restrição para iOS API Places

1 Você pode usar uma chave de API sem restrição com qualquer API ou SDK da Plataforma Google Maps. No entanto, é altamente recomendável restringir as chaves, principalmente nos seguintes cenários:

  • O ambiente de teste será ou está visível publicamente.
  • O aplicativo que usa uma chave de API está pronto para ser usado em um ambiente de produção.

2 Em aplicativos para dispositivos móveis, é recomendável usar o SDK do Maps para Android e o SDK do Maps para iOS nativo.

3 Para a API Maps Static e a API Street View Static, além de uma chave de API, você precisa disponibilizar uma assinatura digital para exceder a cota diária de 25 mil carregamentos de mapa.

Observação: as chaves secretas compartilhadas usadas para assinatura exigem pelo menos o mesmo nível de segurança das chaves de API usadas com as APIs Maps Web Service.

Se você precisar assinar suas solicitações de imagem dinamicamente, faça isso do lado do servidor. Se os aplicativos dependem de entrada do lado do cliente para gerar as imagens estáticas, proteja-as com uma ou mais das seguintes técnicas:

Se você assina suas solicitações, reveja também quantas solicitações não assinadas gostaria de permitir por dia, e ajuste as cotas conforme necessário.

4 As restrições de IP podem ser inviáveis, como em aplicativos para dispositivos móveis e ambientes na nuvem que dependem de endereços IP dinâmicos. Ao usar as APIs Maps Web Service nesses cenários, proteja seus apps empregando uma ou mais das técnicas abaixo:

5 Em aplicativos para dispositivos móveis, é recomendável usar o SDK do Places para Android e o SDK do Places para iOS nativo.