Práticas recomendadas da chave de API

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 o aplicativo 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.

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. As solicitações para usar APIs ou SDKs associados a uma chave de API serão processadas, enquanto as solicitações 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.

Além disso, 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, considere usar o SDK do Places para Android e o SDK do Places para iOS nativo.