Il metodo chat dell'API di dati fornisce l'accesso programmatico ad Ask Advisor in Google Analytics, un assistente analitico basato sull'AI che ti aiuta a eseguire query, analizzare e diagnosticare i dati di Google Analytics utilizzando il linguaggio naturale.
Mentre Ask Advisor è disponibile in modo interattivo nell'interfaccia utente di Google Analytics, l'API chat consente a sviluppatori, agenti AI autonomi e strumenti interni di interagire con Ask Advisor 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 turno singolo sia sessioni di conversazione multi-turno:
- Query a turno singolo: fai 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ù passaggi: passa un
sessionIdper mantenere la cronologia delle conversazioni e porre domande di approfondimento diagnostiche (ad esempio, "Perché il traffico organico è diminuito in quel periodo?"). - Risposte con dati strutturati: oltre alle narrazioni di testo, le risposte contengono blocchi
tablestrutturati con intestazioni di colonna e righe. - Monitoraggio della quota di chat: controlla le quote di token di chat giornaliere e orarie rimanenti 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 assegnare 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 tracciamento delle quote
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 della proprietà
propertyQuota.
{
"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 a più turni
Per porre una domanda aggiuntiva mantenendo il contesto, includi nella richiesta il sessionId restituito dalla risposta precedente.
Scenario: confronto con il periodo precedente
In seguito al confronto dei dispositivi precedente, chiedi ad Advisor 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
Ask 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 componenti strutturati nell'array blocks:
| Tipo di blocco | Campo | Descrizione |
|---|---|---|
| Testo narrativo | blocks[].text |
Spiegazione leggibile e conclusioni analitiche di alto livello. |
| Tabella strutturata | blocks[].table |
Suddivisione dei dati tabulari 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 semantici:
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 Ask 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 temporale scorrevole oraria e saldo rimanente.
Applicazioni di integrazione suggerite
Il metodo properties.chat sblocca diverse architetture di integrazione tra team e strumenti:
Bot di chat e collaborazione aziendale
Collega l'area di lavoro della chat del tuo team direttamente a Google Analytics.
- Sessioni in thread: archivia il
sessionIdcon l'ID thread della chat per consentire ai membri del team di porre domande aggiuntive in modo collaborativo. - Rendering delle schede interattive: formatta i blocchi di risposta di
tablein widget di schede interattive.
Agenti AI autonomi e strumenti Model Context Protocol (MCP)
Fornisci agli orchestratori LLM (come Gemini, LangChain o Claude) uno strumento di analisi GA:
- Anziché forzare un LLM a generare query
runReportcomplesse, l'agente LLM può richiamare il metodochatcon un intent in linguaggio naturale. - L'agente riceve riepiloghi altamente oggettivi e tabelle strutturate da sintetizzare in consigli di marketing multicanale.
Briefing e avvisi esecutivi automatizzati
Crea servizi pianificati che analizzano in modo proattivo le anomalie:
- Un cron job giornaliero esegue query: "Riassumi le metriche sul rendimento principali 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.
Passaggi successivi
- Prova il notebook di Colab interattivo Chiedi ad Advisor per eseguire query a turno singolo e multi-turno utilizzando la libreria client Python.
- Consulta il riferimento API REST
properties.chat. - Scopri di più su quote e limiti dell'API di dati.