Gestione della quota per l'API di dati di Google Analytics

Minhaz Kazi, consulente per gli sviluppatori, Google Analytics – febbraio 2023

Se sviluppi applicazioni utilizzando l'API Google Analytics Data, devi comprendere come funzionano le quote e i limiti per l'API. Se la tua applicazione è ben progettata, è meno probabile che gli utenti raggiungano i limiti di quota. Alcune delle best practice pertinenti portano anche a query efficienti per l'API. Ciò può velocizzare i report e i dashboard nella tua applicazione e migliorare l'esperienza utente. Questo articolo descrive il sistema di quote e le best practice per l'implementazione dell'API Google Analytics Data.

Informazioni sul sistema di quote per l'API Google Analytics Data

Poiché Google Analytics è utilizzato da milioni di sviluppatori e utenti, la quota per le richieste API protegge il sistema dall'elaborazione di una quantità di dati superiore a quella che può gestire, garantendo al contempo una distribuzione equa delle risorse di sistema. L'API di dati per le proprietà Google Analytics 4 utilizza un sistema di token bucket per gestire le quote API. Per comprendere il concetto: immagina che ci sia un bucket che può contenere un numero massimo di token. Qualsiasi richiesta API controllerà prima il bucket. Se non sono rimasti token, la richiesta non andrà a buon fine. In caso contrario, la richiesta verrà eseguita e consumerà uno o più token dal bucket a seconda della sua complessità. I token vengono reintegrati nel bucket fino al massimo a intervalli di tempo fissi.

A seconda del metodo dell'API Data che utilizzi, esistono tre categorie di quote distinte:

I metodi dell'API Google Analytics Data controlleranno più bucket per i [token di quota][quote dell'API di dati di Google Analytics]:

  1. Per proprietà al giorno
  2. Per proprietà all'ora
  3. Per progetto, per proprietà, all'ora
  4. Richieste in parallelo per proprietà
  5. Errori del server per progetto, per proprietà, all'ora

Questi cinque bucket vengono controllati ogni volta che viene ricevuta una richiesta dell'API Data per una proprietà. Se uno dei bucket è vuoto, la richiesta non va a buon fine immediatamente e viene visualizzato un errore 429. Se nessuno dei bucket è vuoto, verrà utilizzato un singolo token dal bucket Richieste in parallelo per proprietà e poi verrà eseguita la richiesta API. In base alla complessità della richiesta, al termine dell'esecuzione verrà consumata una determinata quantità di token da ciascuno dei primi tre bucket. Anche il Numero di richieste in parallelo per proprietà riceverà un token in questo momento.

La quota Per progetto per proprietà all'ora garantisce che l'esaurimento della quota per uno o più utenti non influisca sugli altri utenti della tua applicazione. In questo caso, progetto si riferisce al progetto GCP della tua applicazione. La quota Per proprietà all'ora è in genere quattro volte la quota Per progetto per proprietà all'ora. Pertanto, per gli utenti finali, è necessario accedere a una proprietà da almeno quattro progetti diversi prima che la quota Per proprietà all'ora possa essere esaurita. L'applicazione della quota a livello di progetto e proprietà garantisce che i problemi di quota siano limitati a una singola proprietà e non influiscano sulle altre proprietà a cui accede la tua applicazione.

La quota Errori del server si riferisce alle risposte dell'API con codici 500 o 503. Se la tua applicazione genera troppi errori durante l'accesso a una proprietà, esaurirà la quota Errori del server per progetto per proprietà all'ora.

Tutti i token di quota vengono reintegrati fino al limite a intervalli prestabiliti. Per informazioni aggiornate sulle quote, consulta [Quote dell'API Google Analytics Data]. Ad esempio, i metodi Core ricevono 1250 token di quota nel bucket Per progetto per proprietà per ora. Supponendo che una richiesta media della tua applicazione consumi 10 token quota, la tua applicazione potrà effettuare 125 richieste Core all'ora per una proprietà standard e 10 volte questo importo (1250 richieste Core) per qualsiasi proprietà Analytics 360. Il limite di token della quota più elevato è uno dei principali vantaggi delle proprietà Analytics 360.

Poiché il consumo di token per i primi tre bucket dipende dalla complessità della richiesta, è difficile prevedere l'utilizzo esatto dei token prima dell'esecuzione della richiesta. Di solito, quanto segue aumenta la complessità di una richiesta, con conseguente utilizzo di token:

  • Richiesta di più dimensioni
  • Esecuzione di query su un intervallo di tempo più ampio
  • Inclusione di dimensioni con cardinalità più elevata
  • Eseguire query su una proprietà con un conteggio eventi più elevato

Pertanto, la stessa query per due proprietà diverse potrebbe comportare un utilizzo di token completamente diverso, poiché la cardinalità delle dimensioni potrebbe variare o il volume di traffico potrebbe essere diverso. Tuttavia, puoi aspettarti che le proprietà con livelli di traffico simili e configurazione simile abbiano un utilizzo simile dei token. Puoi utilizzare questo presupposto per prevedere l'utilizzo dei token dei clienti durante le fasi di pianificazione e progettazione dell'applicazione.

Monitoraggio dell'utilizzo della quota

Per monitorare l'utilizzo della quota e comunicare queste informazioni all'utente finale, puoi aggiungere "returnPropertyQuota": true al corpo della richiesta API. Verrà restituito l'oggetto PropertyQuota insieme alla risposta dell'API. L'oggetto PropertyQuota conterrà gli importi di consumo e lo stato della quota rimanente per tutti e cinque i bucket. Ecco un esempio di corpo della richiesta e risposta:

Richiesta

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

Risposta

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

Pertanto, dopo ogni richiesta API di dati riuscita, puoi vedere la quota consumata dalla richiesta e la quota rimanente per la proprietà. È anche possibile mostrare queste informazioni all'utente tramite l'interfaccia dell'applicazione.

Gestione delle quote

Ti consigliamo di implementare le best practice per la gestione delle quote descritte di seguito per ottenere il massimo dall'API Data. Inoltre, l'upgrade delle proprietà a 360 può aumentare la quantità di dati a cui si accede tramite l'API.

Best practice

Esistono due modi principali per ridurre l'utilizzo della quota per la tua applicazione:

  • Invio di un numero inferiore di richieste API
  • Invio di richieste API meno complesse

Tenendo a mente questi due principi, ecco le pratiche che puoi implementare:

  • Memorizzazione nella cache:l'implementazione di un livello di memorizzazione nella cache migliorerà sia l'usabilità che la gestione delle quote per la tua applicazione. Google Analytics memorizzerà nella cache le tue richieste API, ma le richieste ripetute comporteranno comunque l'utilizzo di token di quota. Memorizzando nella cache la risposta dell'API, puoi ridurre drasticamente il numero di richieste ripetute. Ad esempio, i dati infragiornalieri per le proprietà standard possono avere un tempo di scadenza della cache di 4 ore o superiore. Consulta Aggiornamento dei dati per Google Analytics.
  • Unione delle richieste:prova a unire più richieste API in una sola. Ad esempio, 5 richieste di dati in un periodo di 2 giorni potrebbero utilizzare 3 volte i token di quota rispetto a 1 richiesta per un periodo di 10 giorni. Se hai più richieste che variano solo per una dimensione, valuta la possibilità di unirle in un'unica richiesta.
  • Semplificazione delle richieste:limita le richieste alla quantità minima di dati richiesta dalla tua applicazione e dall'utente. Un numero elevato di righe/colonne o criteri di filtro complessi consumeranno più token di quota. Gli intervalli di date più lunghi sono in genere più costosi (ad es. il passaggio da un intervallo di date di 28 giorni a 365 giorni può consumare il triplo dei token quota). Puoi anche prendere in considerazione l'utilizzo di dimensioni con cardinalità inferiore, se possibile (ad es. richiedi dateHour anziché dateHourMinute).
  • Utilizzo efficace di limit: la modifica di limit nella richiesta API per ridurre il numero di righe restituite non influisce in modo significativo sui token di quota consumati. Ad esempio, 5 richieste con limiti di 10.000 righe possono consumare cinque volte i token di quota rispetto a una richiesta con un limite di 50.000.
  • Utilizzo della categoria di metodi corretta:come accennato in precedenza, i limiti di quota sono distribuiti in tre categorie di metodi. L'utilizzo del metodo giusto per il caso d'uso corretto può farti risparmiare quota in altre categorie. Ad esempio, anziché creare una canalizzazione personalizzata nella tua applicazione utilizzando i dati dei metodi Core, utilizza il metodo runFunnelReport per creare canalizzazioni.
  • Aggiorna le impostazioni predefinite:quando creano o personalizzano i report sulla tua piattaforma, gli utenti potrebbero non aggiornare le opzioni predefinite presentate dalla tua applicazione e modificarle solo in fase di runtime. Se la tua applicazione ha un intervallo di date predefinito di 365 giorni e l'utente di solito esamina il report di 28 giorni, questo finirà per consumare più quota del necessario su base regolare. Valuta la possibilità di limitare gli intervalli e le selezioni nelle impostazioni predefinite e lascia che gli utenti selezionino le impostazioni ottimali per i loro casi d'uso. In alcuni casi, puoi anche limitare i valori predefiniti che gli utenti possono modificare.
  • Richieste in coda e caricamento differito:tieni presente il limite di token Richieste simultanee per proprietà. La tua applicazione non deve inviare troppe richieste contemporaneamente. Se la tua applicazione ha un numero elevato di elementi UI che generano un numero significativo di richieste API, valuta la possibilità di impaginare la UI, caricare in modo differito e mettere in coda le richieste con backoff esponenziale per i tentativi. Utilizza il metodo returnPropertyQuota per monitorare in modo aggressivo l'utilizzo dei token Richieste in parallelo per proprietà della tua applicazione.

Gestione dell'esperienza e delle aspettative degli utenti

  • Fornisci feedback agli utenti prima che eseguano query con un potenziale utilizzo elevato di token. Ad esempio, le query con più dimensioni ad alta cardinalità o con un intervallo di tempo ampio potrebbero utilizzare un numero elevato di token. La visualizzazione di un avviso e di una richiesta di conferma per queste query può impedire agli utenti di apportare modifiche non necessarie ai report e aiutarli a limitare l'ambito delle query.
  • Per le soluzioni di reporting personalizzate, fornisci un modo per consentire agli utenti di comprendere l'utilizzo delle query di ogni elemento nel report. Ad esempio, puoi fornire una visualizzazione di debug che elenca l'utilizzo dei token di quota per ogni elemento del report.
  • Fornisci un feedback sul tipo specifico di errore di quota e prescrivi l'azione dell'utente.
  • Poiché le proprietà Google Analytics 360 hanno un limite di quota 5-10 volte superiore rispetto alle proprietà standard, hai una maggiore flessibilità con le proprietà Google Analytics 360.

Gli aumenti delle quote API al di sopra dei limiti predefiniti non sono disponibili per l'API Data di Google Analytics 4. Google Analytics 360 fornisce limiti di quota più elevati per le proprietà Google Analytics 4. Se i tuoi utenti raggiungono i limiti di quota anche dopo aver implementato le best practice, devono valutare la possibilità di eseguire l'upgrade delle proprietà a 360. Un'altra opzione per gli utenti è utilizzare BigQuery Export di Google Analytics. In questo modo, gli utenti potranno esportare i dati a livello di evento in BigQuery ed eseguire le proprie analisi.

Per ulteriori domande sulle quote dell'API Data, visita GA Discord o fai una domanda su Stack Overflow. Se hai richieste di funzionalità specifiche relative all'API Data, puoi pubblicarle nel nostro Issue Tracker.