API Maps JavaScript: gerar uma chave de API ou um ID do cliente

Observação: o plano Premium da Plataforma Google Maps não está mais disponível para inscrições ou novos clientes.

Como escolher um método de autenticação

Para usar a API Maps JavaScript, faça o seguinte:

  • Os clientes com o plano Premium podem usar uma chave de API ou um ID do cliente para autenticar solicitações.
  • Os clientes com uma licença anterior precisam usar um ID do cliente.

Veja a seguir um resumo das ferramentas e dos relatórios disponíveis para cada método de autenticação:

  • Autenticação com uma chave de API (plano Premium)
    Ao usar uma chave de API para autenticar sua solicitação, você pode fazer o seguinte:
    • Gerenciar todas as suas APIs na página "APIs" no Console do Google Cloud
    • Acessar dados de uso em tempo real e dados históricos dos últimos 30 dias no Console do Cloud
    • Adicionar o parâmetro channel às solicitações para ver relatórios de uso mais detalhados
    • Ver relatórios de uso com mais de 30 dias de dados no Console do Cloud
  • Autenticação com um ID do cliente (plano Premium ou licença anterior)
    Ao usar um ID do cliente para autenticar sua solicitação, você pode fazer o seguinte:
    • Adicionar o parâmetro channel às solicitações para ver relatórios de uso mais detalhados
    • Ver relatórios de uso com mais de 30 dias de dados no Console do Cloud
    • Usar as ferramentas de análise do Google Maps para a API Maps JavaScript

Veja mais informações sobre os relatórios disponíveis para clientes do plano Premium.

Autenticação usando uma chave de API

Como criar chaves de API

A chave de API é um identificador exclusivo que autentica solicitações associadas ao seu projeto para fins de uso e faturamento. Você precisa ter pelo menos uma chave de API associada ao projeto.

Para criar uma chave de API, siga estas etapas:

  1. Na página do seletor de projetos, no Console do Google Cloud, escolha ou crie um projeto do Google Cloud a que você quer adicionar uma chave de API.

    Acessar a página do seletor de projetos

    Observação: para ter acesso total aos recursos do plano, os clientes Premium precisam usar o projeto associado a essa conta. Ao comprar sua licença, você recebeu o nome do recurso Premium no seguinte formato: gme-[company] > proj-[number] ([type]). Para garantir que você está acessando o projeto correto, faça login no console como proprietário usando o link console.cloud.google.com/project/number (substitua number pelo número do seu projeto). Você encontrará o proprietário do projeto na mensagem de boas-vindas.

  2. Acesse a página Plataforma Google Maps > Credenciais.

    Acessar a página "Credenciais"

  3. Na página Credenciais, clique em Criar credenciais > Chave de API.
    A caixa de diálogo Chave de API criada exibirá sua chave recém-criada.
  4. Clique em Fechar.
    A nova chave aparecerá na página Credenciais, em Chaves de API.
    Lembre-se de restringir a chave de API antes de usá-la na produção.

Adicionar a chave de API ao seu app

Você precisa incluir uma chave de API em todas as solicitações da Plataforma Google Maps. No exemplo a seguir, substitua YOUR_API_KEY pela sua chave.

<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
type="text/javascript"></script>

O HTTPS é requerido e recomendado, respectivamente, para solicitações que usam uma chave de API e um ID do cliente. Este protocolo também é necessário para aplicativos que incluem dados confidenciais de usuários nas solicitações, como a localização.

Restringir chaves de API

Essa ação aumenta a segurança do aplicativo, garantindo que somente solicitações autorizadas sejam feitas com sua chave de API. Recomendamos que você siga as instruções para definir restrições nessas chaves. Para mais informações, consulte Práticas recomendadas de segurança da API.

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

  1. Acesse a página Plataforma Google Maps > Credenciais.

    Acessar a página "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, defina as seguintes opções:
    • Restrições do aplicativo:
      1. Para aceitar as solicitações da lista de sites que você informou, selecione Referenciadores HTTP (sites da Web) na lista de Restrições do aplicativo.
      2. Especifique um ou mais sites de referenciadores. Por exemplo, *.google.com aceita todos os sites que terminam em google.com, como https://developers.google.com.

        Observação: os referenciadores de file:// precisam de uma representação especial para serem adicionados à restrição de chave. A parte "file://" precisa ser substituída por "__file_url__" antes de ser incluída. Por exemplo, "file:///path/to/" precisa ser formatado como "__file_url__//path/to/*". Depois de ativar os referenciadores de file://, é recomendável verificá-los regularmente para garantir que eles atendam às suas expectativas.

    • Restrições de API:
      1. Clique em Restringir chave.
      2. Escolha Plataforma Google Maps no menu suspenso Selecionar APIs. Se essa opção não aparecer, será preciso ativá-la.
      3. Caso seu projeto use a Biblioteca do Places, selecione também a API Places. Além disso, se ele usa outros serviços na API JavaScript (Directions Service, Distance Matrix Service, Elevation Service e/ou Geocoding Service), também será necessário ativar e selecionar a API correspondente nessa lista.
  4. Para concluir as alterações, clique em Salvar.

Autenticação usando um ID do cliente

Após comprar a licença do plano Premium da Plataforma Google Maps, você receberá um e-mail de boas-vindas do Google contendo o ID do cliente, que permite acessar vários relatórios e ferramentas específicos ao plano.

Todos os IDs de cliente começam com o prefixo gme-. Veja abaixo o formato típico de um ID.

gme-[empresa] > proj-[número] ([tipo])

Você pode autenticar suas solicitações com a API Maps JavaScript usando um ID do cliente em combinação com o registro de URL (em vez de uma chave de API).

Observação: esse ID do cliente não é uma chave e só pode ser usado por URLs autorizados por você. Leia mais sobre como registrar URLs autorizados.

Especificar um ID do cliente ao carregar a API

O código abaixo mostra como substituir YOUR_CLIENT_ID pelo seu próprio ID do cliente ao carregar a API Maps JavaScript.

  <script async defer
  src="https://maps.googleapis.com/maps/api/js?client=YOUR_CLIENT_ID&v=quarterly&callback=initMap"></script>

É necessário especificar a versão de lançamento (também chamada de versão de recurso estável) ou uma versão anterior anexando um parâmetro v=quarterly. Os aplicativos que usam a versão experimental não são cobertos pelo SLA do plano Premium da Plataforma Google Maps.

Observação: se você usava uma chave de API para autenticação e está trocando por um ID do cliente, remova o parâmetro key antes de carregar a API. A API não será carregada se um ID do cliente e uma chave de API estiverem incluídos.

Registrar URLs autorizados

Para impedir que um terceiro use seu ID do cliente no site dele, esse código fica restrito a uma lista de URLs autorizados por você.

Para ver os URLs autorizados ou para autorizar novos URLs, faça o seguinte:

  1. Faça login no Console do Google Cloud.
  2. No menu à esquerda, clique em Maps: gerenciar ID do cliente.

É possível adicionar até 100 URLs de uma vez. Um ID do cliente pode ser associado a no máximo 3.000 URLs autorizados. Se o seu aplicativo hospedar conteúdo do Google Maps de mais de 3.000 locais, use as chaves de API.

As considerações a seguir aplicam-se aos URLs autorizados:

O nome do domínio ou endereço IP não deve ser acessível pelo público em geral.
Por exemplo, http://myintranet e http://192.168.1.1 são entradas válidas.
Todos os subdomínios de um domínio específico também estão autorizados.
Por exemplo, se http://example.com for autorizado, http://www.example.com também será. No entanto, o inverso não é verdadeiro. Por exemplo, se http://www.example.com for autorizado, http://example.com não necessariamente será.
Todos os subcaminhos de um caminho autorizado estão autorizados.
Por exemplo, se http://example.com for autorizado, http://example.com/foo também será. Além disso, como os subdomínios de um domínio especificado também são autorizados, http://sub.example.com/bar também será.
Os caminhos diferenciam maiúsculas e minúsculas.
Por exemplo, http://www.example.com/ThisPath/ não é o mesmo que http://www.example.com/thispath/.
Você pode restringir URLs válidos aos que usam determinadas portas.
Por exemplo, especificar http://example.com:8080/foo não autoriza http://example.com.
Os protocolos HTTP e HTTPS são considerados URLs diferentes.
Por exemplo, se https://example.com for autorizado, http://example.com não necessariamente será.

Todas as regras acima se aplicam a toda autorização. Por isso, planeje suas autorizações com cautela. Por exemplo, como todos os subcaminhos de determinado caminho estão autorizados, além de todos os subdomínios, você pode acabar autorizando páginas que não pretende. Por exemplo:

http://example.com/ também autoriza http://sub.example.com/path.

Para mais informações, consulte Solução de problemas de autorização de URL do plano Premium da Plataforma Google Maps.