Die Methode chat der Data API bietet programmatischen Zugriff auf Ask Advisor in Google Analytics – einen KI-basierten Analytics-Assistenten, mit dem Sie Ihre Google Analytics-Daten in natürlicher Sprache abfragen, analysieren und diagnostizieren können.
Ask Advisor ist interaktiv in der Google Analytics-Benutzeroberfläche verfügbar. Mit der chat API können Entwickler, autonome KI-Agenten und interne Tools jedoch programmatisch über HTTP mit Ask Advisor interagieren.
Wichtig: Dieses Produkt basiert auf künstlicher Intelligenz (KI) und kann fehlerhafte Informationen anzeigen. Ihre Chat-Aktivitäten können zur Verbesserung des Produkts verwendet werden. Ihre Nutzung unterliegt den Nutzungsbedingungen, der Richtlinie zur Nutzung von KI und der Datenschutzerklärung von Google.
Übersicht
Die Methode chat ermöglicht sowohl Ad-hoc-Datenfragen mit einer einzelnen Antwort als auch Unterhaltungen mit mehreren Antworten:
- Single-Turn-Abfragen: Stellen Sie direkte analytische Fragen (z. B. „Welche waren unsere wichtigsten Traffic-Kanäle in der letzten Woche?“) und erhalten Sie Antworten in natürlicher Sprache sowie strukturierte Datentabellen.
- Mehrfachdialoge: Übergeben Sie eine
sessionId, um den Unterhaltungsverlauf beizubehalten und diagnostische Folgefragen zu stellen (z. B. „Warum ist der organische Traffic in diesem Zeitraum zurückgegangen?“). - Antworten mit strukturierten Daten: Neben Textantworten enthalten die Antworten strukturierte
table-Blöcke mit Spaltenüberschriften und Zeilen. - Überwachung des Chatkontingents: Prüfen Sie die verbleibenden täglichen und stündlichen Chat-Token-Kontingente, indem Sie
returnPropertyQuotaauftruesetzen.
Authentifizierung
Für Aufrufe der Methode chat ist eine OAuth 2.0-Autorisierung mit dem folgenden Bereich erforderlich:
Hinweis
Installieren und initialisieren Sie die gcloud CLI.
Führen Sie den folgenden Befehl aus, um Standardanmeldedaten für Anwendungen zu generieren und Ihrem Konto die erforderlichen Bereiche zuzuweisen:
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"Gewähren Sie Ihrem Nutzerkonto auf der Google Analytics-Benutzeroberfläche Zugriff auf eine Google Analytics-Property.
Konfigurieren Sie Ihre Umgebungsvariablen. Dazu geben Sie Folgendes ein. Ersetzen Sie
PROJECT_IDdurch die ID Ihres Projekts von undPROPERTY_IDdurch die ID Ihrer Google Analytics-Property.export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
Beispiel 1: Einzelrunden-Abfrage mit Kontingent-Tracking
Wenn Sie eine neue Unterhaltung beginnen möchten, erstellen Sie eine ChatRequest mit Ihrer userQuery.
Setzen Sie returnPropertyQuota auf true, um Ihr verbleibendes Tokenguthaben zu prüfen.
Szenario: Umsatz und Conversion-Rate nach Gerät
Sie möchten den Umsatz und die Sitzung – Conversion-Rate auf verschiedenen Geräten in den letzten 30 Tagen vergleichen.
HTTP-Anfrage
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
}'
HTTP-Antwort
Die Antwort enthält Folgendes:
- Eine neu zugewiesene
sessionId, die Sie für Folgefragen verwenden können. - Eine Liste von
blocks, die sowohl eine Zusammenfassung in natürlicher Sprache (text) als auch eine strukturierte Tabelle (table) enthält. Textblöcke können Markdown-Formatierungen wie Fettdruck, Überschriften und Links enthalten. - Die
propertyQuota-Details der Unterkunft.
{
"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
}
}
}
Beispiel 2: Diagnose in mehreren Schritten
Wenn Sie eine Folgefrage stellen und den Kontext beibehalten möchten, fügen Sie die sessionId, die von der vorherigen Antwort zurückgegeben wurde, in Ihre Anfrage ein.
Szenario: Mit dem vorherigen Zeitraum vergleichen
Anschließend an den vorherigen Gerätevergleich bitten Sie den Advisor, die Ergebnisse mit dem vorherigen Zeitraum zu vergleichen.
HTTP-Anfrage
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."
}'
HTTP-Antwort
Ask Advisor verwendet den Sitzungsspeicher, um die Ergebnisse mit dem vorherigen Zeitraum zu korrelieren.
{
"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%"
}
]
}
}
}
]
}
Antwortstruktur und Datenblöcke
Das Objekt ChatResponse gibt strukturierte Komponenten im Array blocks zurück:
| Blockierungstyp | Feld | Beschreibung |
|---|---|---|
| Narrative Text | blocks[].text |
Menschenlesbare Erklärung und allgemeine analytische Erkenntnisse. |
| Strukturierte Tabelle | blocks[].table |
Aufschlüsselung tabellarischer Daten mit headers (Namen und Datentypen) und rows (Zellwerten). |
Datentypen für Tabellenkopfzeilen
Spalten in blocks[].table.headers beschreiben den semantischen Datentyp:
string: Kategorische Textwerte (z.B."desktop","/shop/apparel").float: Numerische Gleitkommazahlen.
Kontingentverwaltung für Chat
Anfragen an Ask Advisor verbrauchen Chat-Tokens, je nachdem, wie komplex die Anfrage ist.
Der aktuelle Kontingentstatus wird in propertyQuota zurückgegeben, wenn returnPropertyQuota den Wert true hat:
tokensPerDay: Tageslimit für Tokens und verbleibendes Guthaben.tokensPerHour: Stündliches gleitendes Zeitfenster-Ratenlimit und verbleibendes Guthaben.
Vorgeschlagene Integrationsanwendungen
Die Methode properties.chat ermöglicht verschiedene Integrationsarchitekturen für Teams und Tools:
Enterprise-Chat- und -Zusammenarbeitsbots
Verknüpfen Sie Ihren Teamchat-Arbeitsbereich direkt mit Google Analytics.
- Thread-Sitzungen: Speichern Sie die
sessionIdmit der Chat-Thread-ID, damit Teammitglieder gemeinsam weiterführende Fragen stellen können. - Rendering von interaktiven Chat-Nachrichten: Formatiert
table-Antwortblöcke in interaktive Karten-Widgets.
Autonome KI-Agenten und MCP-Tools (Model Context Protocol)
Statten Sie LLM-Orchestratoren (wie Gemini, LangChain oder Claude) mit einem GA-Analysetool aus:
- Anstatt ein LLM zu zwingen, komplexe
runReport-Abfragen zu generieren, kann der LLM-Agent die Methodechatmit einer Absicht in natürlicher Sprache aufrufen. - Der KI-Agent erhält Zusammenfassungen mit hoher Faktizität und strukturierte Tabellen, die er zu kanalübergreifenden Marketingempfehlungen zusammenfassen kann.
Automatisierte Executive Briefings und Benachrichtigungen
Erstellen Sie geplante Dienste, die Anomalien proaktiv untersuchen:
- Ein täglicher Cronjob fragt ab: „Fasse die wichtigsten Leistungsmesswerte von gestern zusammen und identifiziere alle ungewöhnlichen Rückgänge bei den Conversions.“
- Wenn eine Anomalie gefunden wird, löst das Script automatisch eine Folgeabfrage aus, um die Ursachen zu diagnostizieren, und veröffentlicht eine Zusammenfassung in internen Dashboards oder CRM-Systemen.
Nächste Schritte
- Probieren Sie das interaktive Colab-Notebook „Ask Advisor“ aus, um mit der Python-Clientbibliothek Abfragen mit einer oder mehreren Runden auszuführen.
- Sehen Sie sich die
properties.chatREST API-Referenz an. - Weitere Informationen zu Kontingenten und Limits für die Data API