API Core Reporting - Autorizzazione

Questa guida descrive in che modo un'applicazione autorizza le richieste all'API di reporting principale.

Autorizzazione delle richieste

Prima di poter visualizzare le informazioni del proprio account sul sito web di Google Analytics, gli utenti devono accedere ai propri Account Google. Analogamente, la prima volta che gli utenti accedono all'applicazione, devono autorizzarla ad accedere ai propri dati.

Ogni richiesta che l'applicazione invia all'API Analytics deve includere un token di autorizzazione. Il token, inoltre, identifica l'applicazione per Google.

Informazioni sui protocolli di autorizzazione

La tua applicazione deve utilizzare il protocollo OAuth 2.0 per autorizzare le richieste. Non sono supportati altri protocolli di autorizzazione. Se la tua applicazione utilizza la funzionalità Accedi con Google, alcuni aspetti dell'autorizzazione vengono gestiti per te.

Autorizzazione delle richieste con OAuth 2.0

Tutte le richieste all'API Analytics devono essere autorizzate da un utente autenticato.

I dettagli della procedura di autorizzazione, o "flusso", per il protocollo OAuth 2.0 variano a seconda del tipo di applicazione che stai scrivendo. La seguente procedura generale si applica a tutti i tipi di applicazione:

  1. Quando crei la tua applicazione, la registri utilizzando la console API di Google. Quindi, Google fornisce informazioni che ti saranno necessarie in un secondo momento, ad esempio un ID client e un client secret.
  2. Attiva l'API Analytics nella Console API di Google. (Se l'API non è elencata nella console API, salta questo passaggio.)
  3. Quando la tua applicazione vuole accedere ai dati dell'utente, chiede a Google un particolare ambito di accesso.
  4. Google mostra una schermata di consenso all'utente, chiedendo di autorizzare l'applicazione a richiedere dei dati.
  5. Se l'utente approva, Google fornisce alla tua applicazione un token di accesso di breve durata.
  6. L'applicazione richiede i dati utente, allegando il token di accesso alla richiesta.
  7. Se Google ritiene validi la richiesta e il token, restituisce i dati richiesti.

Alcuni flussi includono passaggi aggiuntivi, come l'uso di token di aggiornamento per acquisire nuovi token di accesso. Per informazioni dettagliate sui flussi per vari tipi di applicazioni, consulta la documentazione relativa al protocollo OAuth 2.0 di Google.

Ecco le informazioni sull'ambito OAuth 2.0 per l'API Analytics:

Ambito Significato
https://www.googleapis.com/auth/analytics.readonly Accesso in sola lettura all'API Analytics.

Per richiedere l'accesso utilizzando il protocollo OAuth 2.0, l'applicazione richiede le informazioni relative all'ambito e le informazioni che Google fornisce quando registri la tua applicazione (ad esempio l'ID client e il client secret).

Suggerimento: le librerie client delle API di Google possono gestire parte del processo di autorizzazione per te. Sono disponibili per una varietà di linguaggi di programmazione; consulta la pagina delle librerie e dei campioni per maggiori dettagli.

Flussi OAuth 2.0 comuni

Di seguito sono elencati i casi d'uso comuni per flussi OAuth 2.0 specifici:

Server web

Questo flusso è adatto per l'accesso automatico, offline o pianificato ai dati di Google Analytics di un utente.

Esempio:

  • Aggiornamento automatico delle dashboard utente con i dati più recenti di Google Analytics.

Lato client

Questo flusso è ideale per le applicazioni quando gli utenti interagiscono direttamente con l'applicazione per accedere ai propri dati di Google Analytics all'interno di un browser. Elimina la necessità di funzionalità lato server, ma rende poco pratici la generazione di report automatici, offline o pianificati.

Esempio:

Applicazioni installate

Questo flusso è per le applicazioni distribuite come pacchetto e installate dall'utente. Questo flusso richiede che l'applicazione o l'utente abbia accesso a un browser per completare il flusso di autenticazione.

Esempi:

  • Un widget desktop su PC o Mac.
  • Plug-in per un sistema di gestione dei contenuti: il vantaggio di questo flusso rispetto al server web o al lato client è che per la tua applicazione può essere utilizzato un singolo progetto della console API. In questo modo è possibile creare report consolidati e semplificare l'installazione per gli utenti.

Account di servizio

Gli account di servizio sono utili per l'accesso automatico, offline o pianificato ai dati di Google Analytics per il tuo account. Ad esempio, creare una dashboard dal vivo contenente i tuoi dati di Google Analytics e condividerli con altri utenti.

Per iniziare a utilizzare l'API Analytics, devi prima utilizzare lo strumento di configurazione, che ti guida nella creazione di un progetto nella console API di Google, nell'attivazione dell'API e nella creazione delle credenziali.

Per configurare un nuovo account di servizio:

  1. Fai clic su Crea credenziali > Chiave account di servizio.
  2. Scegli se scaricare la chiave pubblica/privata dell'account di servizio come file P12 standard o come file JSON che può essere caricato da una libreria client API di Google.

Viene generata e scaricata sul tuo computer una nuova coppia di chiave pubblica/privata, che sarà l'unica copia esistente. Sei responsabile di conservarli in sicurezza.

Risolvere i problemi

L'autorizzazione non va a buon fine nei seguenti casi:

  • Riceverai un codice di stato 401 se access_token è scaduto o se stai utilizzando un ambito errato per l'API.

  • Riceverai un codice di stato 403 se l'utente autorizzato non ha accesso alla vista (profilo). Assicurati di disporre dell'autorizzazione con l'utente corretto e che quest'ultimo disponga della vista (profilo) che hai selezionato.

OAuth 2.0 Playground

Questo strumento ti permette di seguire l'intero flusso di autorizzazione attraverso un'interfaccia web. Lo strumento visualizza anche tutte le intestazioni delle richieste HTTP necessarie per eseguire una query autorizzata. Se non riesci a ottenere l'autorizzazione per utilizzare la tua applicazione, dovresti provare a farla funzionare tramite il parco giochi OAuth 2.0. Successivamente, puoi confrontare le intestazioni e le richieste HTTP del parco giochi con ciò che la tua applicazione invia a Google Analytics. Questo controllo è un modo semplice per assicurarti di formattare correttamente le tue richieste.

Concessione non valida

Quando provi a utilizzare un token di aggiornamento, viene restituito un errore invalid_grant:

Le applicazioni possono richiedere più token di aggiornamento per accedere a un singolo account Google Analytics.

Ad esempio, se un utente vuole installare un'applicazione su più computer e accedere allo stesso account Google Analytics, è necessario un token separato per ogni computer. Quando il numero di token di aggiornamento supera il limite, quelli meno recenti non sono più validi. Se l'applicazione tenta di utilizzare un token di aggiornamento invalidato, viene restituita una risposta di errore invalid_grant.

Il limite per ogni coppia univoca di client OAuth 2.0 e account Google Analytics è di 25 token di aggiornamento. Se l'applicazione continua a richiedere token di aggiornamento per la stessa coppia di client/account, una volta emesso il 26° token, il primo token di aggiornamento emesso in precedenza non sarà più valido. Il 27° token di aggiornamento richiesto renderà non valido il 2° token emesso in precedenza e così via.