Quote e limiti dell'API di dati

I seguenti limiti e quote si applicano all'API di dati.

Come vengono applicate le quote

Tutte le richieste all'API Google Analytics Data v1 richiedono un progetto Google Cloud e sono soggette alle quote descritte in questa pagina. Le quote vengono consumate indipendentemente dal metodo utilizzato per identificare il progetto chiamante, tra cui:

  • Richieste autenticate con credenziali OAuth 2.0.
  • Richieste autenticate utilizzando solo una chiave API.

Le chiavi API vengono utilizzate per associare una richiesta a un progetto cloud Google Cloud specifico per scopi di quota e fatturazione. Tutte le chiamate API effettuate utilizzando le credenziali o una chiave API del tuo progetto verranno conteggiate ai fini delle quote applicabili del progetto e della proprietà Google Analytics.

Categorie di quote

L'API di dati ha quattro categorie di quote di richieste: Core, Realtime, Funnel e Chat.

Le richieste API ai metodi Core addebitano le quote Core. Le richieste API ai metodi Realtime vengono addebitate in base alle quote di Realtime. Le richieste API ai metodi Funnel addebitano quote Funnel. Le richieste API ai metodi Chat vengono addebitate alle quote di Chat. Ogni richiesta consuma un solo tipo di quota.

Categoria di quota Metodi dell'API
Definizione runReport, runPivotReport, batchRunReports, batchRunPivotReports, runAccessReport, getMetadata, checkCompatibility, createAudienceExports
In tempo reale runRealtimeReport
Canalizzazione runFunnelReport
Chat properties.chat

Quote delle proprietà Analytics

Tutte le richieste consumano le quote della proprietà.

Nome quota Limite delle proprietà standard Limite delle proprietà Analytics 360
Token principali per proprietà al giorno 200.000 2.000.000
Token principali per proprietà all'ora 40.000 400.000
Token principali per progetto per proprietà all'ora 14.000 140.000
Richieste in parallelo principali per proprietà 10 50
Errori del server principale per progetto per proprietà all'ora 10 50
Token in tempo reale per proprietà al giorno 200.000 2.000.000
Token in tempo reale per proprietà all'ora 40.000 400.000
Token in tempo reale per progetto per proprietà all'ora 14.000 140.000
Richieste in parallelo in tempo reale per proprietà 10 50
Errori del server in tempo reale per progetto per proprietà all'ora 10 50
Token della canalizzazione per proprietà al giorno 200.000 2.000.000
Token della canalizzazione per proprietà all'ora 40.000 400.000
Token della canalizzazione per progetto per proprietà all'ora 14.000 140.000
Richieste in parallelo di canalizzazione per proprietà 10 50
Errori del server della canalizzazione per progetto per proprietà all'ora 10 50
Token di chat per proprietà al giorno 3.750.000 3.750.000
Token di chat per proprietà all'ora 500.000 500.000
  • Le richieste in parallelo vengono misurate in base al numero di richieste eseguite contemporaneamente. Per ridurre la contemporaneità delle richieste, attendi il completamento delle richieste precedenti prima di inviarne altre.
  • Gli errori del server sono i codici 500 e 503. Le quote per gli errori del server vengono addebitate solo quando una richiesta genera un errore del server. Quando le quote di errori del server sono esaurite per una coppia di proprietà e progetto, tutte le richieste alla proprietà dal progetto vengono bloccate. Per un elenco completo delle risposte di errore, consulta Risposte di errore.
  • Ogni richiesta consuma la quota sia per i token per proprietà all'ora sia per i token per progetto per proprietà all'ora. Ciò significa che una proprietà deve essere consultata da più di tre progetti prima che la quota "Token per proprietà all'ora" possa essere esaurita prima della quota "Token per progetto per proprietà all'ora".

Le proprietà possono inviare 120 richieste con soglia potenziale all'ora. Le dimensioni userAgeBracket, userGender, brandingInterest, audienceId e audienceName sono potenzialmente soggette a soglie. Le soglie vengono applicate per impedire a chiunque visualizzi un report di dedurre i dati demografici o gli interessi dei singoli utenti.

Quota di token della proprietà

I token vengono consumati a ogni richiesta alla versione 1 dell'API Google Analytics Data. Il numero di token addebitati dipende dalla complessità della richiesta. Sebbene la maggior parte delle richieste addebiti 10 o meno token, le richieste più complesse (come le query di Ask Advisor chat) ne consumeranno di più.

Fattori che influiscono sul consumo di token

Il costo esatto dei token per una richiesta viene determinato al momento dell'esecuzione, il che rende difficile un calcolo preliminare preciso. Il costo è influenzato da una combinazione di fattori correlati alla richiesta stessa e ai dati sottostanti nella proprietà Google Analytics. I seguenti fattori possono comportare costi più elevati:

  • Numero di righe: richiedi un numero maggiore di righe.
  • Numero di dimensioni e metriche: l'inclusione di un numero maggiore di dimensioni e metriche.
  • Complessità dei filtri: utilizzo di espressioni di filtro complesse.
  • Durata dell'intervallo di date: esecuzione di query su periodi di date più lunghi.
  • Cardinalità dei dati: le dimensioni con cardinalità elevata (molti valori univoci, come pagePath, dimensioni personalizzate) possono aumentare in modo significativo il costo dei token.
  • Volume di eventi della proprietà: le query sulle proprietà con un volume di eventi più elevato possono consumare più token rispetto alla stessa query su una proprietà con meno dati.

Monitoraggio dell'utilizzo dei token

Il modo più efficace per determinare il costo dei token per le tue chiamate API specifiche è includere il parametro "returnPropertyQuota": true nel corpo della richiesta (supportato in runReport, batchRunReports, runPivotReport, batchRunPivotReports, runRealtimeReport e runFunnelReport). La risposta dell'API includerà quindi l'oggetto PropertyQuota, che descrive in dettaglio i token consumati da quella richiesta specifica e i saldi delle quote rimanenti.

Esempio di richiesta con returnPropertyQuota
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ],
  "returnPropertyQuota": true
}
Esempio di payload di risposta propertyQuota

Quando "returnPropertyQuota": true è impostato, la risposta include un oggetto propertyQuota in cui ogni campo contiene un QuotaStatus con numeri interi consumed e remaining:

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    }
  ],
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 199999
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 39999
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 13999
    }
  }
}

Ogni campo in propertyQuota corrisponde a una quota in Quote delle proprietà di Analytics. La tariffa per i token di una singola richiesta API viene detratta contemporaneamente da tokensPerDay, tokensPerHour e tokensPerProjectPerHour. Se un bucket di quota raggiunge il valore 0, le richieste successive a quella proprietà restituiscono un errore 429 RESOURCE_EXHAUSTED.

Best practice per evitare errori 429 RESOURCE_EXHAUSTED
  • Monitora i saldi di remaining in modo dinamico: controlla propertyQuota.tokensPerProjectPerHour.remaining e propertyQuota.tokensPerHour.remaining nelle risposte e limita o metti in pausa i job in background non urgenti quando i token rimanenti scendono al di sotto di una soglia di sicurezza.
  • Raggruppa le query correlate: utilizza batchRunReports o batchRunPivotReports per raggruppare fino a 5 report in un'unica chiamata HTTP e ridurre l'overhead di andata e ritorno HTTP (tieni presente che ogni report in un batch viene comunque conteggiato singolarmente per le quote di token e concurrentRequests).
  • Riduci la complessità e la cardinalità delle query: limita le richieste solo alle dimensioni e alle metriche necessarie, abbrevia dateRanges, se possibile, ed evita di combinare più dimensioni ad alta cardinalità (ad esempio pagePath o fullPageUrl) nelle query di polling frequenti.
  • Controlla la contemporaneità delle richieste: metti in coda le richieste o limita le dimensioni del pool di worker in modo che le richieste in corso rimangano al di sotto del limite di concurrentRequests (10 per Standard, 50 per Analytics 360).
  • Implementa il backoff esponenziale con limiti di nuovi tentativi: se una richiesta non va a buon fine con 429 RESOURCE_EXHAUSTED, 500 INTERNAL o 503 UNAVAILABLE, riprova utilizzando il backoff esponenziale troncato come descritto in Risposte di errore.

Monitoraggio e consumo dei token di chat

Per le richieste di Ask Advisor chat, i token rappresentano i costi di calcolo, ragionamento e recupero dei dati sottostanti del modello. Il consumo di token di Chat è influenzato da:

  • Ambito della query e dell'analisi: complessità e ampiezza dell'analisi richiesta.
  • Token di input e output del modello: volume di dati contestuali elaborati e narrativa della risposta generata.
  • Token di ragionamento: passaggi di ragionamento del modello necessari per sintetizzare i risultati.
  • Latenza di esecuzione: tempo di elaborazione richiesto per le esplorazioni dei dati in più passaggi.

Per monitorare l'utilizzo dei token di chat, imposta "returnPropertyQuota": true nel tuo ChatRequest. La risposta includerà l'oggetto PropertyChatQuota contenente i campi tokensPerDay e tokensPerHour con i saldi consumati e rimanenti.