Guida alla migrazione dell'ID cliente

Panoramica

Per aumentare la sicurezza e l'affidabilità dell'autenticazione, gli ID client di Maps Platform sono deprecati dal 26 maggio 2025 e non potranno più essere utilizzati dopo il 31 maggio 2026.

Anziché utilizzare un ID client, devi utilizzare le credenziali della chiave API per autenticare il traffico del servizio API di Google Maps. Questa guida mostra come eseguire la migrazione dall'utilizzo degli ID client all'utilizzo delle chiavi API.

Per iniziare, procedi nel seguente modo:

  1. Controlla l'utilizzo attuale dell'ID client
  2. Prepara le chiavi API
  3. Rivedi le impostazioni delle quote
  4. Aggiorna il codice
  5. Monitora il traffico dell'ID client
  6. Metti in pausa l'ID client

Controlla l'utilizzo attuale dell'ID client

Prima di iniziare la procedura di migrazione, elenca quanto segue:

  • Servizi Maps Platform che utilizzi con il tuo ID client.
  • Applicazioni, siti o sistemi con cui utilizzi il tuo ID client.

A maggio 2025, Google ha inviato un'email di notifica ai clienti interessati in merito alla deprecazione dell'ID client. Puoi trovare queste informazioni anche nell'email di notifica.

Nella console Cloud, puoi controllare lo stato più recente dell'utilizzo dell'ID client nella pagina delle metriche di Google Maps

Per un elenco dei servizi Maps Platform:

  1. Apri la pagina Metriche nella console Cloud.
  2. Filtra l'utilizzo con le seguenti impostazioni:
    • Credenziali: seleziona solo "project_number:<numerical identifier>".
  3. Imposta il seguente filtro.
    • Raggruppato per: API

Per suggerimenti su applicazioni, siti o sistemi:

La console Cloud non mostra i dettagli delle tue applicazioni, dei tuoi siti o dei tuoi sistemi. Tuttavia, puoi trovare alcuni suggerimenti sulle origini del traffico dell'ID client. Procedi nel seguente modo:

  1. Apri la pagina Metriche nella console Cloud.
  2. Seleziona un servizio Maps Platform dal menu a discesa.
  3. Filtra l'utilizzo con le seguenti impostazioni:
    • Credenziali: seleziona solo "project_number:<numerical identifier>".
  4. Imposta il seguente filtro.
    • Raggruppa per: piattaforma o dominio
  5. Ripeti i passaggi dal 2 in poi per ogni servizio Maps Platform di cui devi controllare il traffico.

Prepara le chiavi API

Tutti gli ID client sono associati a un progetto Google Cloud e l'utilizzo di una chiave API di questo progetto ti darà accesso alle stesse funzionalità a cui accedevi in precedenza con il tuo ID client. Ti consigliamo di eseguire la migrazione al progetto associato per evitare problemi con le quote o funzionalità mancanti.

  1. Trova il progetto Cloud a cui è collegato il tuo ID client:
  2. Assicurati che il tuo progetto Cloud sia collegato a un account di fatturazione aperto.
  3. Crea una nuova chiave API per la migrazione dell'ID client.
    • Puoi riutilizzare le chiavi API esistenti nel progetto Cloud.
    • Puoi utilizzare più chiavi API dello stesso progetto Cloud, ad esempio per separare il traffico di ogni servizio Maps Platform o per separare il traffico di piattaforme diverse (browser, app mobile e così via). Consulta la guida alla sicurezza per le best practice sulla gestione delle chiavi API.

Proteggi la tua chiave API

Assicurati di proteggere la chiave API per evitare accessi non autorizzati.

  • Imposta una limitazione delle applicazioni per la chiave API (ad es. siti web, indirizzi IP, app per Android o per iOS).
  • Imposta le limitazioni delle API per la chiave API.

Per maggiori dettagli, consulta le indicazioni sulla sicurezza di Google Maps Platform.

Per l'API Maps JavaScript, l'API Maps Static e l'API Street View Static, puoi migrare i referrer attendibili sul tuo ID client alle limitazioni delle chiavi API. Puoi trovare l'elenco dei referrer attendibili nella console Cloud.

Rivedi le impostazioni delle quote

Assicurati di aver configurato le impostazioni delle quote previste nel tuo progetto Cloud. Devi farlo solo se chiami i servizi lato client dell'API Maps JavaScript da un ID client. Puoi controllare e modificare le impostazioni delle quote nella pagina delle quote di Google Maps.

Scopri di più sui report sulle quote

Aumento delle quote per i servizi lato client dell'API Maps JavaScript

Se utilizzi i seguenti servizi nell'API Maps JavaScript, vedrai aumentare l'utilizzo delle quote dopo la migrazione della chiave API.

Rivedi la configurazione delle quote attuale, l'utilizzo corrente e modifica i limiti delle quote di conseguenza.

  1. Verifica se utilizzi i servizi lato client dell'API Maps JavaScript con un ID client.
    • Apri la pagina Metriche nella console Cloud.
    • Filtra l'utilizzo con le seguenti impostazioni:
      • Raggruppato per: metodo API
      • Credenziali: seleziona solo "project_number:<numerical identifier>".
    • Verrà visualizzato un elenco di nomi di metodi con il relativo traffico nel grafico "Traffico per metodo API".

Metodo API

Servizio lato client

Servizio per modificare la quota

google.routes.Directions.Javascript

Servizio Directions

API Directions

google.routes.DistanceMatrix.Javascript

Servizio Distance Matrix

API Distance Matrix

google.maps.Elevation.Javascript

Servizio Elevation

API Elevation

google.places.Geocoding.Javascript

Servizio Geocoding

API Geocoding

google.places.*.Javascript, diverso da google.places.Geocoding.Javascript

Libreria Places

API Places
  • Se non utilizzi questi metodi API, non devi preoccuparti delle impostazioni delle quote, perché il traffico dell'ID client consuma già la quota del progetto.
  • Stima l'utilizzo delle quote dell'ID client
    • Per ogni servizio, controlla sia la granularità al secondo sia quella giornaliera.
    • Grafico al secondo: moltiplica il traffico di picco per 60 per le esigenze di quota aggiuntive al minuto.
    • Grafico giornaliero: il traffico di picco deve essere la quota aggiuntiva necessaria al giorno.
  • Modifica la quota nei servizi Maps Platform corrispondenti
    • In base al nome del metodo che trovi nel passaggio 1, modifica la quota nei servizi corrispondenti.

Aggiorna il codice

Sostituisci il parametro client con il parametro key

Aggiorna le credenziali di autenticazione da URL&client={value} a URL&key={value} nelle chiamate API GMP in uscita. Se le tue app utilizzano HTTP per accedere ai servizi GMP, aggiornale in modo che utilizzino HTTPS.

Aggiorna il parametro channel per i report

Puoi monitorare l'utilizzo per canale specificando il parametro channel nelle richieste API. Le chiavi API supportano solo valori numerici per il parametro channel. Se utilizzi l'ID client con valori non numerici per il parametro channel, aggiornalo a un valore numerico supportato.

Per ulteriori informazioni, consulta la sezione Report di Google Maps Platform.

Rimuovi il parametro signature per i servizi web

Per le seguenti API dei servizi web, il parametro signature non è necessario quando vi accedi con una chiave API. Rimuovi il parametro signature solo dalle richieste API.

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

Per ulteriori informazioni, consulta la panoramica del piano Premium.

Signing secret per le API Imagery

L'API Maps Static e l'API Street View Static richiedono ancora il parametro signature. Accettano un numero limitato di richieste senza firma a scopo di test, ma iniziano a non riuscire quando raggiungono la soglia in produzione. Sostituisci il signing secret da quello per l'ID client a quello per la chiave API. Puoi utilizzare lo stesso algoritmo di firma, ma devi utilizzare un altro signing secret. Per scoprire di più, consulta la sezione Utilizzare una firma digitale.

Monitora il traffico dell'ID client

Dopo il deployment, verifica che la migrazione del traffico sia andata a buon fine utilizzando le dashboard della console Cloud. Inizierai a notare una diminuzione del traffico dell'ID client, visualizzato nel formato "project_number:123456" nella dashboard quando raggruppi per credenziali.

Metti in pausa l'ID client

Ti consigliamo vivamente di mettere in pausa gli ID client dopo la migrazione. In questo modo, proteggi le tue credenziali da qualsiasi traffico indesiderato e confermi che qualsiasi utilizzo rimanente dell'ID client non sia critico (ad es. test, cache, bot e così via) e possa restituire errori senza causare un impatto sull'attività. Puoi mettere in pausa l'ID client nella console Cloud. Per maggiori dettagli, consulta la panoramica sull'autenticazione del piano Premium.

Risoluzione dei problemi

Come possiamo verificare se la nostra richiesta non va a buon fine?

Puoi controllare le statistiche sugli errori nei grafici dei codici di risposta

Errore ApiNotActivatedMapError o REQUEST_DENIED

Se non hai abilitato il servizio nel tuo progetto Cloud, verrà visualizzato l'errore ApiNotActivatedMapError o REQUEST_DENIED. Segui le istruzioni per abilitare il servizio.

Errore RefererNotAllowedMapError

Se il dominio di origine non è stato aggiunto alla chiave API, verrà visualizzato l'errore RefererNotAllowedMapError. Consulta la sezione "Proteggi la tua chiave API" e aggiungi il tuo dominio alla chiave API.

Errore OverQuotaMapError o OVER_QUERY_LIMIT

Se la quota configurata non è sufficiente a coprire il traffico, verrà visualizzato l'errore OverQuotaMapError o OVER_QUERY_LIMIT. Consulta la sezione "Rivedi le impostazioni delle quote" e modifica la quota di conseguenza.

Errore "Requests to this API must be over SSL"

Se ricevi il seguente messaggio di errore, aggiorna le richieste API da "http://" a "https://".

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

  "results" : [],

  "status" : "REQUEST_DENIED"
}