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 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. Você também pode encontrar 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 seu uso com as seguintes configurações:
   • Credenciais: selecione apenas "project_number:<identificador numérico>".
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 origens do tráfego do seu ID de 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 seu uso com as seguintes configurações:
   • Credenciais: selecione apenas "project_number:<identificador numérico>".
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 do cliente estão associados a um projeto do Google Cloud. Usar uma chave de API desse projeto vai dar acesso aos mesmos recursos que você acessava com o ID do cliente. Recomendamos migrar para o projeto associado para evitar problemas com cotas ou recursos ausentes.

1. Encontre o projeto na nuvem vinculado ao seu ID do cliente:
   • 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 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 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 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. Você encontra a lista de referenciadores confiáveis no console do Cloud.

Revisar as configurações de cota

Verifique se você tem as configurações de cota esperadas no seu projeto na nuvem. 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. Verifique e ajuste as configurações de cota na página de cotas do Google Maps.

Saiba mais sobre os relatórios de cota

Aumento de 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 atuais de cota 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 o uso com as seguintes configurações:
     • Agrupados por: método de API
     • Credenciais: selecione apenas "project_number:<numerical identifier>".
   • Em seguida, você vai ver uma lista de nomes de métodos com o tráfego deles no gráfico "Tráfego por método da 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 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 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 do GMP. Se seus apps estiverem usando HTTP para acessar 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 seu ID do cliente com valores não numéricos para o parâmetro "channel", atualize 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 para 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 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 Imagery

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 pela 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 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.

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á restringido periodicamente como parte do processo programado de encerramento do serviço. Embora o serviço seja restaurado automaticamente em algumas horas, você pode reativar o acesso manualmente se precisar de uma restauração imediata.

Para restaurar o acesso com urgência, faça uma reativação de autoatendimento pelo 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 retomar, localizado na extremidade direita da entrada, para restaurar o serviço.

Se você não conseguir migrar rapidamente para chaves de API e quiser uma isenção temporária de mais 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 Client-ID nos 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 elas, 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 conta de subfaturamento desejada.
3. Agrupe 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. Para identificar o tráfego do ID do cliente, procure entradas em que o rótulo goog-maps-api-key-suffix está ausente ou vazio, já que ele 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 SKUs de assinatura.

Solução de problemas

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

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

ApiNotActivatedMapError ou erro REQUEST_DENIED

Você vai receber o erro ApiNotActivatedMapError ou REQUEST_DENIED se não tiver ativado o serviço no seu projeto na nuvem. 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 à sua chave de API. Confira a seção "Proteger sua chave de API" e adicione seu domínio à chave de API.

OverQuotaMapError ou erro OVER_QUERY_LIMIT

Você vai ver o OverQuotaMapError ou o 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 sua cota de acordo com a necessidade.

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

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