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

Minhaz Kazi, Developer Advocate, Google Analytics – Febbraio 2023

Se sviluppi applicazioni utilizzando l'API di dati di Google Analytics, devi comprendere come funzionano le quote e i limiti per l'API. Se la tua applicazione è progettata correttamente, è meno probabile che gli utenti raggiungano i limiti di quota. Alcune delle best practice pertinenti portano anche a query ad alte prestazioni all'API. In questo modo, i report e le dashboard nell'applicazione possono velocizzare i report e le dashboard e, quindi, rendere l'esperienza utente più desiderabile. Questo articolo illustra il sistema di quote e le best practice per l'implementazione dell'API di dati di Google Analytics.

Informazioni sul sistema delle quote per l'API di dati di Google Analytics

Poiché Google Analytics viene utilizzato da milioni di sviluppatori e utenti, la quota per le richieste API protegge il sistema dall'elaborazione di più dati di quanti sia in grado di 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 bucket di token per gestire le quote dell'API. Per capire il concetto, immagina che esista un bucket che può contenere fino a un numero massimo di token. Qualsiasi richiesta API controllerà prima il bucket. Se non ci sono più token, la richiesta avrà esito negativo. In caso contrario, la richiesta verrà eseguita e consumerà uno o più token dal bucket, a seconda della complessità della richiesta. I token vengono reintegrati nel bucket al massimo a intervalli di tempo fissi.

A seconda del metodo dell'API di dati in uso, esistono tre categorie di quote distinte:

• In tempo reale (per runRealtimeReport)
• Canalizzazione (per runFunnelReport)
• Core (per tutti gli altri metodi)

E i metodi dell'API di dati controlleranno più bucket per i token di quota:

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 arriva una richiesta dell'API di dati per una proprietà. Se uno qualsiasi dei bucket è vuoto, la richiesta non andrà a buon fine immediatamente e verrà visualizzato un errore 429. Se nessuno dei bucket è vuoto, verrà utilizzato un singolo token dal bucket Richieste in parallelo per proprietà e 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. Al momento viene reintegrato anche un token Richieste in parallelo per proprietà.

La quota Per progetto per proprietà all'ora garantisce che l'esaurimento della quota per uno o più utenti non influisca sugli altri utenti dell'applicazione. In questo caso, progetto fa riferimento al progetto GCP dell'applicazione. La quota Per proprietà all'ora è generalmente quattro volte superiore a quella Per progetto per proprietà all'ora. Pertanto, per gli utenti finali, una proprietà deve essere accessibile da almeno quattro diversi progetti prima di poter esaurire la quota Per proprietà all'ora. L'applicazione della quota sia a livello di progetto che di proprietà garantisce che i problemi di quota siano limitati a una singola proprietà e non influiscano sulle altre proprietà a cui l'applicazione accede.

Avviso: gli sviluppatori sono vivamente sconsigliati a utilizzare i token di quota per lo sharding in più progetti API. Si tratta di una violazione dei Termini di servizio delle API di Google.

La quota Errori del server si riferisce alle risposte dell'API con codici 500 o 503. Se l'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 stabiliti. Per informazioni aggiornate sulle quote, consulta Quote dell'API di dati di Google Analytics. Ad esempio, i metodi principali ricevono 1250 token di quota nel bucket Per progetto per proprietà all'ora. Supponendo che una richiesta media dalla tua applicazione utilizzi 10 token di quota, l'applicazione sarà in grado di effettuare 125 richieste principali all'ora per una proprietà standard e 10 volte tale quantità (1250 richieste principali) per qualsiasi proprietà Analytics360. Il limite di token di quota più elevato è uno dei principali vantaggi delle proprietà Analytics 360.

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

• Richiedere più dimensioni
• Esecuzione di query su un intervallo di tempo più elevato
• Inclusione di dimensioni con cardinalità più elevata
• Esecuzione di query su una proprietà con un numero di eventi più elevato

Pertanto, la stessa query per due proprietà diverse potrebbe comportare un utilizzo dei token completamente diverso, poiché la cardinalità delle dimensioni potrebbe variare o il volume di traffico potrebbe essere diverso. Tuttavia, le proprietà con livelli di traffico e configurazioni simili potrebbero avere un utilizzo simile dei token. Puoi usare questa ipotesi per prevedere l'utilizzo dei token dei clienti durante le fasi di pianificazione e progettazione dell'applicazione.

Nota: se in precedenza hai utilizzato l'API di reporting per Universal Analytics, noterai che l'API di reporting ha applicato la quota a livello di progetto applicazione/API. Tuttavia, per l'API di dati, l'applicazione avviene a livello di proprietà Google Analytics e di progetto API.

Monitoraggio dell'utilizzo della quota

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

Richiedi

{
  "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",
  ...
}

Quindi, dopo ogni richiesta API di dati riuscita, puoi aspettarti di vedere quanta quota ha consumato la richiesta e quanta quota è rimasta per la proprietà. È anche possibile mostrare queste informazioni all'utente tramite l'interfaccia dell'applicazione.

Nota: nella fase attuale dell'API di dati, devi eseguire correttamente una richiesta API per recuperare l'oggetto PropertyQuota. Se la proprietà ha già esaurito un bucket di token di quota, la richiesta avrà esito negativo con un errore 429 e la risposta non conterrà l'oggetto PropertyQuota. Se questa situazione ti riguarda e ritieni che la tua applicazione possa trarre vantaggio dall'avere un modo separato per accedere alle informazioni sulla quota, fai +1 su questa richiesta di funzionalità su Issue Tracker.

Gestione delle quote

Ti consigliamo di implementare le best practice di gestione della quota descritte di seguito per ottenere il massimo dall'API di dati. 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 per ridurre l'utilizzo della quota per l'applicazione:

• Invio di meno richieste API
• Invio di richieste API meno complesse.

Tenendo a mente questi due principi, ecco alcune prassi che puoi adottare:

• Memorizzazione nella cache: l'implementazione di un livello di memorizzazione nella cache darà vantaggio sia all'usabilità che alla gestione delle quote per la tua applicazione. Google Analytics memorizza nella cache le richieste API, ma le richieste ripetute comportano comunque token di quota. Se memorizzi la risposta dell'API nella cache, puoi ridurre drasticamente il numero di richieste ripetute. Ad esempio, i dati infragiornalieri per le proprietà standard possono avere una scadenza di 4 ore o superiore. Consulta Aggiornamento dei dati per Google Analytics.
• Richieste di unione: prova a unire più richieste API in una singola. Ad esempio, 5 richieste di dati in un intervallo di tempo di 2 giorni potrebbero utilizzare il triplo dei token di quota rispetto a una 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.
• Semplificare le richieste: limita le richieste alla quantità minima di dati richiesta dall'applicazione e dall'utente. Un numero elevato di righe/colonne o criteri di filtro complessi consumano più token di quota. Gli intervalli di date più lunghi sono in genere più costosi (ad esempio, la modifica dell'intervallo di date da 28 giorni a 365 giorni può consumare il triplo dei token di quota). Puoi anche prendere in considerazione l'utilizzo di dimensioni con cardinalità più bassa quando possibile (ad esempio, richiedi dateHour anziché dateHourMinute).
• Utilizzo effettivo 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 un limite di 10.000 righe possono consumare cinque volte i token di quota rispetto a 1 richiesta con un limite di 50.000.
• Utilizzo della giusta categoria di metodo: come accennato sopra, i limiti di quota sono distribuiti tra tre categorie di metodi. Usare il metodo giusto per il caso d'uso giusto per risparmiare quota su altre categorie. Ad esempio, anziché creare una canalizzazione personale nell'applicazione utilizzando i dati dei metodi principali, utilizza il metodo runFunnelReport per creare le canalizzazioni.
• Aggiorna le impostazioni predefinite: quando crei o personalizzi 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 consulta il report di 28 giorni, ciò consumerà regolarmente più quota del necessario. Valuta la possibilità di limitare gli intervalli e le selezioni nelle impostazioni predefinite e consentire agli utenti di selezionare le impostazioni ottimali per i loro casi d'uso. Oppure, in alcuni casi, puoi anche limitare i valori predefiniti modificabili dagli utenti.
• Coda di richieste e caricamento lento: tieni presente il limite di token Richieste in parallelo 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 impostare l'interfaccia utente in pagine, il caricamento lento e la coda delle richieste con backoff esponenziale per i nuovi tentativi. Utilizza il metodo returnPropertyQuota per monitorare in modo rigoroso l'utilizzo del token Richieste in parallelo per proprietà dell'applicazione.

Gestire l'esperienza utente e le aspettative

• 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 elevato potrebbero utilizzare un numero elevato di token. La fornitura 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 alle loro query.
• Per le soluzioni di generazione di report personalizzate, fornisci agli utenti un modo per comprendere l'utilizzo delle query di ogni elemento del 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 specifica un'azione dell'utente.
• Poiché le proprietà Google Analytics 360 ricevono un limite di quota da 5 a 10 volte superiore rispetto alle proprietà standard, ottieni una maggiore flessibilità con le proprietà Google Analytics 360.

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

Per ulteriori domande sulle quote dell'API di dati, vai a GA Discord o chiedi su Stack Overflow. Se hai richieste di funzionalità specifiche per l'API di dati, puoi pubblicarle nel nostro Issue Tracker.