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

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

Se stai sviluppando applicazioni utilizzando l'API di dati di Google Analytics, dovrebbe capire come funzionano le quote e i limiti per l'API. Se le tue l'applicazione sia ben progettata, gli utenti hanno meno probabilità di raggiungere i limiti di quota. Alcuni di le best practice pertinenti generano query ad alte prestazioni all'API. Questo può velocizzare i report e le dashboard nella tua applicazione e, di conseguenza, un'esperienza utente positiva. Questo articolo illustra il sistema di quote e le best practice per l'implementazione dell'API di dati di Google Analytics.

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

Poiché Google Analytics è utilizzato da milioni di sviluppatori e utenti, quota sull'API impediscono al sistema di elaborare più dati di quanti ne possa gestire garantire una distribuzione equa delle risorse di sistema. L'API di dati per Google Le proprietà Analytics 4 utilizzano un sistema di bucket di token per gestire le quote API. A comprendi il concetto: immagina un bucket che può contenere fino a di token. Qualsiasi richiesta API controllerà prima il bucket. Se non sono presenti rimanenti, la richiesta avrà esito negativo. In caso contrario, la richiesta verrà eseguita consumerà uno o più token dal bucket a seconda della complessità la richiesta. I token vengono reintegrati nel bucket al massimo al valore fisso intervalli di tempo.

A seconda del metodo dell'API di dati che utilizzi, sono disponibili tre quote separate categorie:

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

E i metodi dell'API di dati controlleranno più bucket 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 di API di dati proprietà. Se uno dei bucket è vuoto, la richiesta ha immediatamente esito negativo con un errore 429. Se nessuno dei bucket è vuoto, viene generato verrà utilizzato dal bucket Richieste simultanee per proprietà e la richiesta API verrà eseguita. In base alla complessità della richiesta, viene consumata una certa quantità di token da ciascuno dei primi tre bucket una volta completata l'esecuzione. Anche le richieste in parallelo per proprietà il token viene reintegrato in questo momento.

La quota Per progetto per proprietà all'ora garantisce che l'esaurimento della quota uno o più utenti non avranno effetto sugli altri utenti della tua applicazione. Qui, project fa riferimento al progetto Google Cloud della tua applicazione. La quota Per proprietà all'ora è di solito quattro volte la quota Per progetto per proprietà all'ora. Quindi, per la fine agli utenti, prima di poter accedere a una proprietà è necessario che almeno 4 diversi progetti la quota Per proprietà all'ora può essere esaurita. Applicazione della quota sia a livello di progetto e di proprietà garantisce che i problemi di quota siano limitati a un singolo e non influirà sulle altre proprietà a cui ha accesso la tua applicazione.

Avviso: gli sviluppatori sconsigliano vivamente di eseguire il partizionamento orizzontale dei token di quota tra in più progetti API. Si tratta di una violazione dei Termini di servizio delle API di Google.

La quota di Errori del server si riferisce alle risposte dell'API con 500 o Codici 503. Se l'applicazione genera troppi errori mentre accedendo a una proprietà, verranno esauriti gli errori del server per progetto della proprietà per ora.

Tutti i token di quota vengono reintegrati nel limite a intervalli stabiliti. Consulta Quote dell'API di dati di Google Analytics per informazioni aggiornate sulle quote. Ad esempio: I metodi Core ricevono 1250 token di quota in Per progetto per proprietà all'ora. di sincronizzare la directory di una VM con un bucket. Supponiamo che una richiesta media della tua applicazione utilizzi 10 quota l'applicazione potrà effettuare 125 richieste Core all'ora per un standard e 10 volte l'importo (1250 richieste Core) per qualsiasi account Analytics proprietà 360. 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à del la richiesta, è difficile prevedere l'utilizzo esatto dei token prima della richiesta dell'esecuzione. Quanto segue di solito aumenta la complessità di una richiesta, con conseguente utilizzo del token:

• Richiesta di altre dimensioni
• Esecuzione di query su un intervallo di tempo superiore
• 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 generare un utilizzo dei token completamente diverso poiché la cardinalità delle dimensioni vari oppure il volume di traffico potrebbe essere diverso. Tuttavia, puoi aspettarti proprietà con livelli di traffico e configurazione simili per avere un utilizzo simile di token. Puoi utilizzare questa ipotesi per prevedere l'utilizzo dei token del cliente durante le fasi di pianificazione e progettazione dell'applicazione.

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

Monitoraggio dell'utilizzo delle quote

Per monitorare l'utilizzo della quota e comunicare queste informazioni all'utente finale, puoi aggiungere "returnPropertyQuota": true al corpo della richiesta API. Verrà restituito PropertyQuota insieme alla risposta dell'API. L'oggetto PropertyQuota conterrà le quantità di consumo e lo stato di quota rimanente per tutti e cinque 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",
  ...
}

Di conseguenza, dopo ogni richiesta dell'API di dati andata a buon fine, puoi aspettarti quota la richiesta consumata e la quota rimanente per la proprietà. È anche possibile mostrare queste informazioni all'utente tramite l'applicazione. a riga di comando.

Nota: nella fase attuale dell'API di dati, devi eseguire correttamente un Richiesta API per recuperare l'oggetto PropertyQuota. Se la proprietà ha già esaurito un bucket di token di quota, la richiesta non andrà a buon fine con un errore 429 e la risposta non conterrà l'oggetto PropertyQuota. Se il problema riguarda e ritiene che la tua applicazione potrebbe trarre vantaggio dall'avere un modo separato per accedere alle informazioni sulla quota, +1 questa richiesta di funzionalità in Issue Tracker.

Gestione delle quote

Consigliamo di implementare le best practice per la gestione delle quote descritte di seguito per ottenere sfruttare al massimo l'API di dati. Inoltre L'upgrade delle proprietà a 360 può aumentare la quantità ai dati accessibili tramite l'API.

Best practice

In generale, esistono due modi per ridurre l'utilizzo della quota per la tua applicazione:

• Invio di meno 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 apporta vantaggi sia all'usabilità che la gestione delle quote per la tua applicazione. Google Analytics memorizza nella cache le richieste API, ma le richieste ripetute comportano comunque token di quota. Di memorizzando nella cache la risposta API, puoi ridurre drasticamente il numero richieste. Ad esempio, i dati infragiornalieri per le proprietà standard possono avere 4 ore o un tempo di scadenza superiore a quello della cache. Consulta la sezione Aggiornamento dei dati per Google Analisi.
• Unione di richieste: prova a unire più richieste API in una singola. Ad esempio, 5 richieste di dati in un intervallo di tempo di due giorni potrebbero essere utilizzate 3 volte i token di quota rispetto a una richiesta per un intervallo di tempo di 10 giorni. Se disponi più richieste che variano solo per una singola dimensione, valuta la possibilità di unirle in un'unica richiesta.
• Semplificazione delle richieste:limita le richieste alla quantità minima di dati. richiesto dalla tua applicazione e dall'utente. Un numero elevato di righe/colonne oppure con criteri di filtro complessi consumano più token di quota. Intervalli di date più lunghi in genere sono più costosi (ad esempio cambiando l'intervallo di date da 28 giorni a 365) giorni può utilizzare il triplo dei token di quota). Puoi anche valutare l'uso dimensioni con cardinalità più bassa quando possibile (ad es. richiedi dateHour anziché dateHourMinute).
• Utilizzo effettivo di limit: modifica di limit nell'API la richiesta di ridurre il numero di righe restituite non influisce in modo significativo di quota utilizzati. Ad esempio, 5 richieste con un limite di 10.000 righe consuma cinque volte i token di quota rispetto a una richiesta con un limite di 50.000.
• Utilizzo della categoria di metodo corretta: come già detto, i limiti di quota vengono distribuiti in tre categorie di metodi. Usare il metodo giusto per il giusto del caso d'uso può risparmiare quota su altre categorie. Ad esempio, invece di creando la tua canalizzazione nell'applicazione utilizzando i dati dei metodi Core utilizza il metodo runFunnelReport per creare le canalizzazioni.
• Aggiornamento delle impostazioni predefinite: quando crei o personalizzi i report sul tuo gli utenti potrebbero non aggiornare le opzioni predefinite presentate e modifiche solo in fase di runtime. Se la tua applicazione include un intervallo di date predefinito di 365 giorni e di solito l'utente esamina il report di 28 giorni, questo finirà per consumare più quota di quanto richiesto abitualmente. Valuta la possibilità di limitare gli intervalli e le selezioni nelle impostazioni predefinite e consenti gli utenti selezionano le impostazioni ottimali per i loro casi d'uso. Oppure, in alcuni casi, puoi anche limitare le impostazioni predefinite che gli utenti possono modificare.
• Richieste di coda e caricamento lento: tieni presente che le richieste simultanei Limite di token per le richieste per proprietà. La tua richiesta non deve essere inviata troppe richieste contemporaneamente. Se la tua applicazione include un numero elevato di elementi UI che generano un numero significativo di richieste API, considera impaginazione dell'interfaccia utente, caricamento lento e accodamento delle richieste il backoff per i nuovi tentativi. Usa il metodo returnPropertyQuota per in modo aggressivo monitorare l'utilizzo dei token Richieste simultanee per proprietà dell'applicazione.

Gestire l'esperienza utente e le aspettative

• Fornisci un feedback agli utenti prima che eseguano query con un utilizzo potenzialmente elevato dei token. Ad esempio, le query con più dimensioni ad alta cardinalità o con un un periodo di tempo più lungo potrebbe utilizzare un numero elevato di token. Fornire un avviso e un una richiesta di conferma per queste query può impedire agli utenti di modifiche non necessarie ai report e limitare l'ambito ai propri query.
• Per soluzioni di generazione di report personalizzate, offri agli utenti un modo per capire l'utilizzo delle query per ogni elemento del report. Ad esempio, puoi fornire una visualizzazione di debug che elenca l'utilizzo dei token di quota per ciascun elemento del report.
• Fornisci un feedback sul tipo specifico di errore di quota e indica l'impostazione un'azione.
• Poiché le proprietà Google Analytics 360 hanno un limite di quota da 5 a 10 volte superiore rispetto a quello alle proprietà standard, ottieni maggiore flessibilità con Google Analytics 360 proprietà.

Gli aumenti della quota dell'API che superano i limiti predefiniti non sono disponibili per l'API di dati per Google Analytics 4. Google Analytics 360 prevede limiti più elevati per le quote Proprietà Google Analytics 4. Se i tuoi utenti raggiungono i limiti della quota e dopo aver implementato le best practice, dovrebbero valutare l'upgrade proprietà a 360. Un'altra opzione per gli utenti è quella di utilizzare BigQuery Export di Google Analytics. In questo modo, gli utenti potranno esportare i dati a livello di evento a BigQuery ed eseguire la propria analisi.

Per ulteriori domande sulle quote dell'API di dati, consulta GA Discord oppure chiedi su Stack Overflow. Se hai richieste di funzionalità specifiche in merito ai API, puoi pubblicarli sul nostro strumento di monitoraggio dei problemi.