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 le credenziali OAuth 2.0.
• Richieste autenticate utilizzando solo una chiave API.

Le chiavi API vengono utilizzate per associare una richiesta a un progetto 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, In tempo reale, Canalizzazione e Chat.

Le richieste API ai metodi Core addebitano le quote Core. Le richieste API ai metodi in tempo reale addebitano le quote in tempo reale. Le richieste API ai metodi di canalizzazione addebitano le quote di canalizzazione. Le richieste API ai metodi di chat addebitano le quote di chat. Ogni richiesta consuma un solo tipo di quota.

Quote delle proprietà Analytics

Tutte le richieste consumano le quote delle proprietà.

• Le richieste in parallelo vengono misurate in base al numero di richieste eseguite contemporaneamente. Per ridurre la simultaneità delle richieste, attendi il completamento delle richieste precedenti prima di inviare richieste aggiuntive.
• Gli errori del server sono i codici 500 e 503. Le quote degli errori del server vengono addebitate solo quando una richiesta genera un errore del server. Quando le quote degli errori del server vengono esaurite per una coppia progetto-proprietà, tutte le richieste alla proprietà dal progetto vengono bloccate. Per un elenco completo delle risposte di errore, consulta Error Responses.
• 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 è necessario che più di tre progetti accedano a una proprietà prima che la quota "Token per proprietà all'ora" possa essere esaurita prima della quota "Token per progetto per proprietà all'ora".

Alle proprietà sono consentite 120 richieste potenzialmente soggette a soglia all'ora. Le dimensioni userAgeBracket, userGender, brandingInterest, audienceId e audienceName sono potenzialmente soggette a soglia. 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 con ogni richiesta all'API Google Analytics Data v1. 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 (ad esempio le query chatdi Ask Advisor ) ne consumeranno di più.

Fattori che influenzano il consumo di token

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

• Numero di righe: richiedere un numero maggiore di righe.
• Numero di dimensioni e metriche: includere un numero maggiore di dimensioni e metriche.
• Complessità del filtro: utilizzare espressioni di filtro complesse.
• Lunghezza dell'intervallo di date: eseguire query su periodi di date più lunghi.
• Cardinalità dei dati: le dimensioni con cardinalità elevata (molti valori unici, ad esempio pagePath, dimensioni personalizzate) possono aumentare notevolmente il costo dei token.
• Volume di eventi della proprietà: le query sulle proprietà con un volume di eventi più elevato potrebbero 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 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 dalla 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 propertyQuota oggetto in cui ogni campo contiene un QuotaStatus con consumed e remaining numeri interi:

{
  "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à Analytics. L'addebito dei token di una singola richiesta API viene detratto contemporaneamente da tokensPerDay, tokensPerHour e tokensPerProjectPerHour. Se un bucket di quote raggiunge 0 rimanenti, le richieste successive a quella proprietà restituiscono un errore 429 RESOURCE_EXHAUSTED.

Best practice per evitare errori 429 RESOURCE_EXHAUSTED

• Monitora remaining dinamicamente i saldi: esamina 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 una singola chiamata HTTP e ridurre il sovraccarico di round trip HTTP (tieni presente che ogni report in un batch viene comunque conteggiato singolarmente ai fini delle quote di token e concurrentRequests).
• Riduci la complessità e la cardinalità delle query: limita le richieste solo alle dimensioni e alle metriche di cui hai bisogno, accorcia dateRanges ove possibile ed evita di combinare più dimensioni ad alta cardinalità (ad esempio pagePath o fullPageUrl) nelle query di polling frequenti.
• Controlla la simultaneità 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 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.

Consumo e monitoraggio dei token di chat

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

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

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