Guia de migração de ID do cliente

Visão geral

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 seu ID do cliente
7. Reativação temporária de autoatendimento do 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 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. Você também encontra essas informações no e-mail de notificação.

No console do Cloud, é possível verificar o status mais recente do uso do ID do cliente na página de métricas do 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:<identificador numérico>".
3. Defina o filtro a seguir.
   • 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 é possível encontrar algumas dicas de origens 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 Maps no menu suspenso.
3. Filtre o uso com as seguintes configurações:
   • Credenciais: selecione apenas "project_number:<identificador numérico>".
4. Defina o filtro a seguir.
   • Agrupar por: plataforma ou domínio
5. Repita a partir da etapa 2 para cada serviço da Plataforma Maps em que você precisa verificar o tráfego.

Preparar chaves de API

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

1. Encontre o projeto na nuvem ao qual seu ID do cliente está vinculado:
   • Perguntas frequentes sobre a migração do portal
2. Verifique se o projeto na nuvem 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 no projeto na nuvem.
   • É possível usar várias chaves de API do mesmo projeto na nuvem, por exemplo, para separar o tráfego de cada serviço da Plataforma Maps ou de plataformas diferentes (navegador, app para dispositivos móveis etc.). Consulte o guia de segurança para ver as práticas recomendadas de gerenciamento de chaves de API.

Proteger sua chave de API

Proteja sua chave de API contra 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 as configurações de cota esperadas estão no seu projeto na nuvem. Isso só é necessário se você estiver chamando os serviços do lado do cliente da API Maps JavaScript usando um ID do cliente. Verifique e ajuste as configurações de cota na página de cotas do Google Maps.

Saiba mais sobre os relatórios de cotas

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

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

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

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:<identificador numérico>".
   • 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".

• 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 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 pico de tráfego por 60 para as necessidades adicionais de cota por minuto.
  • Gráfico por dia: o pico de tráfego deve ser a cota adicional por dia necessária.
• Ajuste sua cota nos serviços correspondentes da Plataforma Google Maps
  • Com base no nome do método que você encontra na Etapa 1, ajuste a cota nos serviços correspondentes.

Atualizar o código

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

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

Atualizar o parâmetro de canal para relatórios

Para acompanhar o uso por canal, 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 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 os Relatórios da Plataforma Google Maps para mais informações.

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

Para as seguintes APIs de serviço 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 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

As APIs Maps Static e 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 o secret de assinatura do ID do cliente pelo da chave de API. É possível usar o mesmo algoritmo de assinatura, mas é necessário usar outro secret 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 usando os painéis do console do Cloud. Você vai começar a 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 serve para proteger suas credenciais de qualquer tráfego não intencional e confirmar 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.

Reativação temporária de autoatendimento do ID do cliente

Como os IDs de cliente da Plataforma Google Maps entraram no período de descontinuação gradual em maio de 2026, a disponibilidade do serviço não é mais garantida. O acesso será restrito periodicamente como parte do processo de encerramento do serviço programado. Embora o serviço geralmente seja restaurado de forma automática em algumas horas, é possível reativar o acesso manualmente se a restauração imediata for necessária.

Para restaurar o acesso com urgência, faça uma reativação de autoatendimento no Console do Google Cloud:

• Acesse a página Credenciais da Plataforma Google Maps.
• Localize o projeto na nuvem específico que está vinculado ao seu ID do cliente.
• Clique no ícone de retomada localizado na extremidade direita da entrada para restaurar o serviço.

Se você não conseguir migrar rapidamente para as chaves de API e quiser uma isenção temporária de outras interrupções, entre em contato com a equipe de suporte da Plataforma Google Maps com os seguintes detalhes:

• ID do cliente
• Caso de uso específico
• Data de migração desejada
• Avaliação de impacto nos negócios

Relatório de uso do ID do cliente: dos relatórios de faturamento

Verificar os relatórios de faturamento em vez das métricas do projeto pode ser útil para usuários que não têm acesso a essas métricas, como administradores de faturamento (especialmente parceiros da Plataforma Maps). Embora os relatórios de faturamento tenham uma latência de 1 a 2 dias, eles têm o benefício de mostrar mais de 30 dias de insights de uso e custo.

Para monitorar o uso do ID do cliente no console do Google Cloud, siga estas etapas:

1. Acesse a página Faturamento > Relatórios no console do Google Cloud.
2. (Opcional, relevante apenas para parceiros) Aplique um filtro para selecionar a subconta de faturamento desejada.
3. Agrupar os dados do relatório pela chave de rótulo goog-maps-api-key-suffix. Esse rótulo mostra os caracteres finais de uma chave de API.
4. Identifique o tráfego do ID do cliente procurando entradas em que o rótulo goog-maps-api-key-suffix esteja ausente ou vazio, já que esse rótulo não é preenchido para solicitações de ID do cliente.
5. Ignore as SKUs que não devem ser associadas a solicitações de API, como as de assinatura.

Solução de problemas

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

Confira as estatísticas de erro 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 ativar o serviço no projeto na nuvem. Siga as instruções para ativar o serviço.

RefererNotAllowedMapError erro

Você vai receber o erro RefererNotAllowedMapError se o domínio de origem não for adicionado à sua 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 ver OverQuotaMapError ou OVER_QUERY_LIMIT se a cota configurada não for suficiente para cobrir o tráfego. Verifique a seção "Analisar configurações de cota" e ajuste sua cota de acordo.

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

Se você receber a mensagem de erro a seguir, atualize suas 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"
}