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, use credenciais de chave de API para autenticar o tráfego de serviço da API Google Maps. Este guia mostra como migrar do uso de IDs de 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 seu código
  5. Monitorar o tráfego do ID do cliente
  6. Pausar seu 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 em 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. Essas informações também estão disponíveis no e-mail de notificação.

No console do Cloud, confira o status mais recente do uso do ID do cliente na página de métricas do Google Maps.

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

  1. Abra a página Métricas no Console do Cloud.
  2. Filtre seu 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. Mas 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 seu 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 partir da 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 do Google Cloud, e usar uma chave de API desse projeto dá acesso aos mesmos recursos que você acessava com seu ID de cliente. Recomendamos migrar para o projeto associado para evitar problemas com cotas ou recursos ausentes.

  1. Encontre o projeto do Cloud a que seu ID de cliente está vinculado:
  2. Verifique se o projeto do Cloud está vinculado a uma conta de faturamento aberta.
  3. Crie uma chave de API para a migração do ID do cliente.
    • É possível reutilizar as chaves de API atuais no projeto do Cloud.
    • É possível 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 de diferentes plataformas (navegador, app para dispositivos móveis etc.). Consulte o guia de segurança para conferir as práticas recomendadas de gerenciamento de chaves de API.

Proteja 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 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 as APIs Maps JavaScript, Maps Static e Street View Static, é possível migrar os referenciadores de confiança 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 seu projeto do Cloud. Você só precisa fazer isso se estiver chamando os serviços do lado do cliente da API Maps JavaScript de um ID do cliente. Você pode 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 sua configuração e uso de cota atuais e ajuste os limites de cota de acordo.

  1. Verifique se você está usando 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 seu uso com as seguintes configurações:
      • Agrupado por: método da 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 da 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, exceto google.places.Geocoding.Javascript

Biblioteca Places

API Places
  • Se você não usa esses métodos de API, não precisa se preocupar com as configurações de cota, já que o tráfego do ID do cliente consome a cota do projeto.
  • Estimar o uso da cota de ID do cliente
    • Para cada um dos serviços, verifique a granularidade "Por segundo" e "Por dia".
    • Gráfico por segundo: multiplique o pico de tráfego por 60 para as necessidades adicionais de cota por minuto.
    • Gráfico por dia: o pico de tráfego precisa 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 parâmetro de cliente por parâmetro de chave

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

Atualizar o parâmetro de canal para geração de relatórios

Para rastrear o uso por canais, especifique o parâmetro "channel" nas solicitações de API. As chaves de API só aceitam valores numéricos para o parâmetro "channel". Se você estiver usando seu ID do cliente com valores não numéricos para o parâmetro "channel", atualize 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 seguintes APIs de serviços da Web, 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 suas 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 de imagens

As APIs Maps Static e Street View Static ainda exigem o parâmetro de assinatura. Eles 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 o segredo de assinatura do ID do cliente pelo da chave de API. Você pode usar o mesmo algoritmo de assinatura, mas precisa usar outro segredo 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 seu ID do cliente

Recomendamos que os desenvolvedores pausem os IDs de cliente após a migração. Isso protege suas credenciais de qualquer tráfego não intencional e confirma que o 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 seu 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?

Confira as estatísticas de erros nos gráficos de código de resposta.

Erro ApiNotActivatedMapError ou REQUEST_DENIED

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

RefererNotAllowedMapError erro

O erro "RefererNotAllowedMapError" vai aparecer se o domínio de origem não for adicionado à chave de API. Confira a seção "Proteja sua chave de API" e adicione seu domínio à chave.

Erro OverQuotaMapError ou OVER_QUERY_LIMIT

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

Erro "As solicitações para esta 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"
}