Guia de migração de ID do cliente

Visão geral

Para aumentar a segurança e a confiabilidade da autenticação, os IDs de cliente da Plataforma Google Maps foram descontinuados em 26 de maio de 2025 e não poderão mais ser usados após 31 de maio de 2026.

Em vez de usar um ID do cliente, você precisa usar credenciais de chave de API para autenticar o tráfego do serviço da API Google Maps. Este guia mostra como migrar do uso de IDs do cliente para o uso de chaves de API.

Siga estas etapas para começar:

  1. Verificar o uso atual do ID do cliente
  2. Preparar chaves de API
  3. Revisar as configurações de cota
  4. Atualizar o código
  5. Monitorar o tráfego do ID do cliente
  6. Pausar o ID do cliente

Verificar o uso atual do ID do cliente

Antes de iniciar o processo de migração, liste o seguinte:

  • Serviços da Plataforma Google Maps que você está usando com seu ID do cliente.
  • Aplicativos, sites ou sistemas com que você está usando seu ID do cliente.

O Google enviou um e-mail de notificação aos clientes afetados sobre a descontinuação do ID do cliente em maio de 2025. Você também pode encontrar essas informações no e-mail de notificação.

No console do Cloud, você pode verificar o status mais recente do uso do ID do cliente na página Métricas da Plataforma Google Maps

Para uma lista de serviços da Plataforma Google Maps:

  1. Abra a página Métricas no console do Cloud.
  2. Filtre o uso com as seguintes configurações:
    • Credenciais: selecione apenas "project_number:<numerical identifier>".
  3. Defina o seguinte filtro.
    • Agrupado por: API

Para dicas de aplicativos, sites ou sistemas:

O console do Cloud não mostra detalhes dos seus aplicativos, sites ou sistemas. No entanto, você pode encontrar algumas dicas de fontes do tráfego do ID do cliente. Siga estas etapas:

  1. Abra a página Métricas no console do Cloud.
  2. Selecione um serviço da Plataforma Google Maps no menu suspenso.
  3. Filtre o uso com as seguintes configurações:
    • Credenciais: selecione apenas "project_number:<numerical identifier>".
  4. Defina o seguinte filtro.
    • Agrupar por: plataforma ou domínio
  5. Repita a etapa 2 para cada serviço da Plataforma Google Maps em que você precisa verificar o tráfego.

Preparar chaves de API

Todos os IDs de cliente estão associados a um projeto na nuvem do Google Cloud, e o uso de uma chave de API desse projeto na nuvem dá acesso aos mesmos recursos que você acessava anteriormente com o ID do cliente. Recomendamos migrar para o projeto associado para evitar problemas com cotas ou recursos ausentes.

  1. Encontre o projeto do Cloud ao qual o ID do cliente está vinculado:
  2. Verifique se o projeto do Cloud está vinculado a uma conta de faturamento aberta.
  3. Crie uma nova chave de API para a migração do ID do cliente.
    • É possível reutilizar as chaves de API atuais no projeto do Cloud.
    • Você pode usar várias chaves de API do mesmo projeto do Cloud, por exemplo, para separar o tráfego de cada serviço da Plataforma Google Maps ou para separar o tráfego de diferentes plataformas (navegador, app para dispositivos móveis etc.). Consulte o guia de segurança para conferir as práticas recomendadas sobre o gerenciamento de chaves de API.

Proteger sua chave de API

Proteja sua chave de API para evitar acesso não autorizado.

  • Defina uma restrição de aplicativo para sua chave de API (por exemplo, sites, endereços IP, apps Android ou apps iOS).
  • Defina restrições de API para sua chave de API.

Para mais detalhes, consulte as orientações de segurança da Plataforma Google Maps.

Para a API Maps JavaScript, a API Maps Static e a API Street View Static, é possível migrar os referenciadores confiáveis no ID do cliente para as restrições de chave de API. A lista de referenciadores confiáveis está disponível no console do Cloud.

Revisar as configurações de cota

Verifique se você tem as configurações de cota esperadas no projeto do Cloud. Só é necessário fazer isso se você estiver chamando os serviços do lado do cliente da API Maps JavaScript de um ID do cliente. É possível verificar e ajustar as configurações de cota na página de cotas do Google Maps.

Saiba mais sobre os relatórios de cota

Aumento da cota para serviços do lado do cliente da API Maps JavaScript

Se você estiver usando os seguintes serviços na API Maps JavaScript, o uso da cota vai aumentar após a migração da chave de API.

Revise a configuração de cota atual, o uso atual e ajuste os limites de cota de acordo com isso.

  1. Verifique se você está usando os serviços do lado do cliente da API Maps JavaScript com um ID do cliente.
    • Abra a página Métricas no console do Cloud.
    • Filtre o uso com as seguintes configurações:
      • Agrupado por: método de API
      • Credenciais: selecione apenas "project_number:<numerical identifier>".
    • Em seguida, você verá uma lista de nomes de métodos com o tráfego no gráfico "Tráfego por método de API".

Método de API

Serviço do lado do cliente

Serviço para ajustar a cota

google.routes.Directions.Javascript

Serviço Directions

API Directions

google.routes.DistanceMatrix.Javascript

Serviço Distance Matrix

API Distance Matrix

google.maps.Elevation.Javascript

Serviço Elevation

API Elevation

google.places.Geocoding.Javascript

Serviço Geocoding

API Geocoding

google.places.*.Javascript, diferente de google.places.Geocoding.Javascript

Biblioteca Places

API Places
  • Se você não usar esses métodos de API, não precisará se preocupar com as configurações de cota, já que o tráfego do ID do cliente já consome a cota do projeto.
  • Estimar o uso da cota do ID do cliente
    • Para cada um dos serviços, verifique a granularidade por segundo e por dia.
    • Gráfico por segundo: multiplique o tráfego de pico por 60 para as necessidades adicionais de cota por minuto.
    • Gráfico por dia: o tráfego de pico deve ser a cota adicional por dia.
  • Ajuste sua cota nos serviços correspondentes da Plataforma Google Maps
    • Com base no nome do método encontrado na etapa 1, ajuste a cota nos serviços correspondentes.

Atualizar o código

Substituir o parâmetro do cliente pelo parâmetro da chave

Atualize as credenciais de autenticação de URL&client={value} para URL&key={value} nas chamadas de API GMP de saída. Se seus apps estiverem usando HTTP para acessar serviços GMP, atualize-os para usar HTTPS.

Atualizar o parâmetro de canal para relatórios

É possível acompanhar o uso por canais especificando o parâmetro de canal para as solicitações de API. As chaves de API só aceitam valores numéricos para o parâmetro de canal. Se você estiver usando o ID do cliente com valores não numéricos para o parâmetro de canal, atualize-o para um valor numérico compatível.

Consulte a Geração de relatórios da Plataforma Google Maps para mais informações.

Remover o parâmetro de assinatura para serviços da Web

Para as APIs de serviço da Web a seguir, o parâmetro de assinatura não é necessário quando você as acessa com uma chave de API. Remova apenas o parâmetro de assinatura das solicitações de API.

  • API Directions (legada)
  • API Distance Matrix (legada)
  • API Geocoding
  • API Elevation
  • API Time Zone

Consulte a Visão geral do plano Premium para mais informações.

Chave secreta de assinatura para APIs Imagery

A API Maps Static e a API Street View Static ainda exigem o parâmetro de assinatura. Elas aceitam um pequeno número de solicitações sem assinatura para fins de teste, mas começam a falhar quando atingem o limite na produção. Substitua a chave secreta de assinatura do ID do cliente pela chave de API. É possível usar o mesmo algoritmo de assinatura, mas é necessário usar outra chave secreta de assinatura. Para saber mais, consulte Usar uma assinatura digital.

Monitorar o tráfego do ID do cliente

Após a implantação, confirme se o tráfego foi migrado com sucesso usando os painéis do console do Cloud. Você vai notar uma diminuição no tráfego do ID do cliente, que é mostrado no formato "project_number:123456" no painel ao agrupar por credencial.

Pausar o ID do cliente

Recomendamos que os desenvolvedores pausem os IDs de cliente após a migração. Isso é para proteger suas credenciais de qualquer tráfego não intencional e confirmar que qualquer uso restante no ID do cliente não é crítico (por exemplo, testes, caches, bots etc.) e pode retornar erros sem causar impacto nos negócios. É possível pausar o ID do cliente no console do Cloud. Consulte a Visão geral da autenticação do plano Premium para mais detalhes.

Solução de problemas

Como podemos saber se nossa solicitação está falhando ou não?

É possível verificar as estatísticas de erros nos gráficos de código de resposta.

Erro ApiNotActivatedMapError ou REQUEST_DENIED

Você vai receber o erro ApiNotActivatedMapError ou REQUEST_DENIED se não tiver ativado o serviço no projeto do Cloud. Siga as instruções para ativar o serviço.

Erro RefererNotAllowedMapError

Você vai receber o erro RefererNotAllowedMapError se o domínio de origem não for adicionado à chave de API. Confira a seção "Proteger sua chave de API" e adicione seu domínio à chave de API.

Erro OverQuotaMapError ou OVER_QUERY_LIMIT

Você vai receber o erro OverQuotaMapError ou OVER_QUERY_LIMIT se a cota configurada não for suficiente para cobrir o tráfego. Confira a seção "Revisar as configurações de cota" e ajuste a cota de acordo com isso.

Erro "As solicitações para essa API precisam ser feitas por SSL"

Se você receber a seguinte mensagem de erro, atualize as solicitações de API de "http://" para "https://".

{
  "error_message" : "Requests to this API must be over SSL. Load the API with
  \"https://\" instead of \"http://\".",

  "results" : [],

  "status" : "REQUEST_DENIED"
}