Il metodo chat dell'API Data fornisce accesso programmatico all'Assistente Analytics, un assistente analitico basato sull'AI che ti aiuta a eseguire query, analizzare e diagnosticare i tuoi dati di Google Analytics utilizzando il linguaggio naturale.
Sebbene l'Assistente Analytics sia disponibile in modo interattivo all'interno dell'interfaccia utente di Google Analytics, l'API chat consente a sviluppatori, agenti AI autonomi e strumenti interni di interagire con l'Assistente Analytics in modo programmatico tramite HTTP.
Importante:questo prodotto utilizza l'AI e potrebbe mostrare informazioni imprecise. La tua attività di chat potrebbe essere utilizzata per migliorare il prodotto e il tuo utilizzo è soggetto ai Termini, alle Norme sull'utilizzo dell'AI e alle Norme sulla privacy di Google.
Panoramica
Il metodo chat consente sia
domande sui dati ad hoc a un solo turno sia sessioni conversazionali multi-turno:
- Query a un solo turno: poni domande analitiche immediate (ad esempio "Quali sono stati i nostri principali canali di traffico la scorsa settimana?") e ricevi risposte in linguaggio naturale insieme a tabelle di dati strutturati.
- Conversazioni in più turni:passa un
sessionIdper mantenere la cronologia della conversazione e porre domande diagnostiche di follow-up (ad esempio, "Perché il traffico organico è diminuito in quel periodo?"). - Risposte con dati strutturati:oltre alle descrizioni testuali, le risposte
contengono blocchi
tablestrutturati con intestazioni di colonna e righe. - Monitoraggio della quota di chat:controlla le quote giornaliere e orarie rimanenti dei token di chat impostando
returnPropertyQuotasutrue.
Autenticazione
Le chiamate al metodo chat
richiedono l'autorizzazione OAuth 2.0 con il seguente ambito:
Prima di iniziare
Installa e inizializza gcloud CLI.
Per generare le credenziali predefinite dell'applicazione e concedere al tuo account gli ambiti necessari, esegui questo comando:
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"Nell'interfaccia utente di Google Analytics, concedi al tuo account utente l'accesso a una proprietà Google Analytics.
Configura le variabili di ambiente inserendo quanto segue. Sostituisci
PROJECT_IDcon l'ID del tuo progetto ePROPERTY_IDcon l'ID della tua proprietà Google Analytics.export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
Esempio 1: query a turno singolo con monitoraggio della quota
Per avviare una nuova conversazione, crea un ChatRequest
contenente il tuo userQuery.
Imposta returnPropertyQuota
su true per controllare il saldo dei token rimanenti.
Scenario: entrate e tasso di conversione per dispositivo
Vuoi confrontare le entrate e il tasso di conversione delle sessioni su più dispositivi negli ultimi 30 giorni.
Richiesta HTTP
curl -X POST \
"https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "x-goog-user-project: ${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{
"userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
"returnPropertyQuota": true
}'
Risposta HTTP
La risposta contiene:
- Un
sessionIdappena assegnato che puoi utilizzare per i turni successivi. - Un elenco di
blockscontenente sia un riepilogo in linguaggio naturale (text) sia una tabella strutturata (table). I blocchi di testo possono contenere la formattazione Markdown, ad esempio testo in grassetto, intestazioni e link. - I dettagli del
propertyQuotadella proprietà.
{
"sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
"blocks": [
{
"text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
},
{
"table": {
"headers": [
{
"header": "Device Category",
"dataType": "string"
},
{
"header": "Total Revenue",
"dataType": "string"
},
{
"header": "User Conversion Rate",
"dataType": "string"
}
],
"rows": [
{
"columns": [
{
"value": "Desktop"
},
{
"value": "$17,412.62"
},
{
"value": "99.9%"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "$15,309.41"
},
{
"value": "99.46%"
}
]
}
}
},
{
"text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
},
{
"text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
}
],
"propertyQuota": {
"tokensPerDay": {
"consumed": 26849,
"remaining": 3723151
},
"tokensPerHour": {
"consumed": 26849,
"remaining": 473151
}
}
}
Esempio 2: diagnostica conversazionale multi-turno
Per porre una domanda aggiuntiva preservando il contesto, includi sessionId restituito dalla risposta precedente nella tua richiesta.
Scenario: confrontare con il periodo precedente
Riprendendo il confronto tra i dispositivi precedente, chiedi al consulente di confrontare i risultati con il periodo precedente.
Richiesta HTTP
curl -X POST \
"https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "x-goog-user-project: ${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
"userQuery": "Compare results with the same period in the previous mounth."
}'
Risposta HTTP
Analytics Advisor utilizza la memoria della sessione per correlare i risultati con il periodo precedente.
{
"sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
"blocks": [
{
"text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
},
{
"table": {
"headers": [
{
"header": "Device Category",
"dataType": "string"
},
{
"header": "Metric",
"dataType": "string"
},
{
"header": "Jul 16 - Aug 15, 2026",
"dataType": "string"
},
{
"header": "Aug 16 - Sep 14, 2026",
"dataType": "string"
}
],
"rows": [
{
"columns": [
{
"value": "Desktop"
},
{
"value": "Total Revenue"
},
{
"value": "$17,412.62"
},
{
"value": "$19,565.46"
}
]
},
{
"columns": [
{
"value": "Desktop"
},
{
"value": "User Conversion Rate"
},
{
"value": "1.90%"
},
{
"value": "1.95%"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "Total Revenue"
},
{
"value": "$13,997.19"
},
{
"value": "$15,309.41"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "User Conversion Rate"
},
{
"value": "1.95%"
},
{
"value": "1.99%"
}
]
}
}
}
]
}
Struttura della risposta e blocchi di dati
L'oggetto ChatResponse
restituisce i componenti strutturati nell'array
blocks:
| Tipo di blocco | Campo | Descrizione |
|---|---|---|
| Narrative Text | blocks[].text |
Spiegazione leggibile e principali risultati analitici. |
| Tabella strutturata | blocks[].table |
Suddivisione dei dati tabellari contenente headers (nomi e tipi di dati) e rows (valori delle celle). |
Tipi di dati dell'intestazione della tabella
Le colonne in
blocks[].table.headers
descrivono il tipo di dati semantico:
string: valori di testo categorici (ad es."desktop","/shop/apparel").float: Numeri in rappresentazione in virgola mobile.
Gestione della quota di chat
Le richieste di Analytics Advisor consumano token di chat in base alla complessità della query. Lo stato attuale della quota viene restituito in propertyQuota quando returnPropertyQuota è true:
tokensPerDay: limite di token giornaliero e saldo rimanente.tokensPerHour: limite di frequenza della finestra mobile oraria e saldo rimanente.
Applicazioni di integrazione suggerite
Il metodo properties.chat
sblocca diverse architetture di integrazione tra team e strumenti:
Bot per la chat e la collaborazione aziendale
Collega il tuo spazio di lavoro di chat di gruppo direttamente a Google Analytics.
- Sessioni in thread:memorizza l'
sessionIdin base all'ID thread della chat per consentire ai membri del team di porre domande di follow-up in modo collaborativo. - Rendering delle schede interattive:formatta i blocchi di risposta
tablein widget di schede interattive.
Agenti AI autonomi e strumenti Model Context Protocol (MCP)
Dotare gli orchestratori LLM (come Gemini, LangChain o Claude) di uno strumento di analisi GA:
- Anziché forzare un LLM a generare query
runReportcomplesse, l'agente LLM può richiamare il metodochatcon intent in linguaggio naturale. - L'agente riceve riepiloghi di alta precisione e tabelle strutturate da sintetizzare in consigli di marketing multicanale.
Avvisi e briefing esecutivi automatizzati
Crea servizi pianificati che analizzano in modo proattivo le anomalie:
- Un cron job giornaliero esegue query: "Riassumi le principali metriche di rendimento di ieri e identifica eventuali cali anomali delle conversioni".
- Se viene rilevata un'anomalia, lo script attiva automaticamente una query di follow-up per diagnosticare le cause principali e pubblica un riepilogo nelle dashboard interne o nei sistemi CRM.