Die Methode chat der Data API bietet programmatischen Zugriff auf Analytics Advisor, einen KI-basierten Analyseassistenten, mit dem Sie Ihre Google Analytics-Daten in natürlicher Sprache abfragen, analysieren und diagnostizieren können.
Analytics 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 Analytics Advisor interagieren.
Wichtig:Dieses Produkt basiert auf künstlicher Intelligenz 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 nur einer Antwort als auch Mehrfachdialog-Konversationssitzungen:
- Einmalige Abfragen:Sie können sofort analytische Fragen stellen, z. B. „Was waren unsere wichtigsten Traffic-Channels in der letzten Woche?“, und erhalten Antworten in natürlicher Sprache sowie strukturierte Datentabellen.
- Mehrfachdialoge:Übergeben Sie ein
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 Textbeschreibungen enthalten Antworten strukturierte
table-Blöcke mit Spaltenüberschriften und Zeilen. - Chatkontingent überwachen:Sie können das verbleibende tägliche und stündliche Chat-Token-Kontingent prüfen, indem Sie
returnPropertyQuotaauftruefestlegen.
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 in der Google Analytics-Benutzeroberfläche Zugriff auf eine Google Analytics-Property.
Konfigurieren Sie Umgebungsvariablen. Dazu geben Sie Folgendes ein. Ersetzen Sie
PROJECT_IDdurch die ID Ihres Projekts undPROPERTY_IDdurch die ID Ihrer Google Analytics-Property.export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
Beispiel 1: Einzelrunden-Anfrage mit Kontingent-Tracking
Wenn Sie eine neue Unterhaltung starten möchten, erstellen Sie ein ChatRequest mit Ihrem userQuery.
Setzen Sie returnPropertyQuota auf true, um Ihr verbleibendes Token-Guthaben 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:
- Ein neu zugewiesener
sessionId, den Sie für weitere Züge 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: Konversationelle Diagnose in mehreren Schritten
Wenn Sie eine Folgefrage stellen möchten, ohne den Kontext zu verlieren, fügen Sie die sessionId aus der vorherigen Antwort in Ihre Anfrage ein.
Szenario: Mit dem vorherigen Zeitraum vergleichen
Sie bitten den Kundenservicemitarbeiter, 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
Analytics Advisor verwendet den Sitzungsspeicher, um Ergebnisse mit dem vorherigen Zeitraum in Beziehung zu setzen.
{
"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 ChatResponse-Objekt gibt strukturierte Komponenten im blocks-Array zurück:
| Blocktyp | Feld | Beschreibung |
|---|---|---|
| Narrativer Text | blocks[].text |
Eine menschenlesbare Erklärung und allgemeine analytische Erkenntnisse. |
| Strukturierte Tabelle | blocks[].table |
Aufschlüsselung der tabellarischen Daten mit headers (Namen und Datentypen) und rows (Zellwerte). |
Datentypen für Tabellenüberschriften
Die Spalten in blocks[].table.headers beschreiben den semantischen Datentyp:
string: Kategorische Textwerte (z.B."desktop","/shop/apparel").float: Numerische Gleitkommazahlen.
Chat-Kontingentverwaltung
Für Anfragen an Analytics Advisor werden Chat-Tokens basierend auf der Komplexität der Anfrage verwendet. Der aktuelle Kontingentstatus wird in propertyQuota zurückgegeben, wenn returnPropertyQuota den Wert true hat:
tokensPerDay: Das tägliche Tokenlimit und der verbleibende Betrag.tokensPerHour: Stündliches Rate Limit mit gleitendem Fenster und verbleibendes Kontingent.
Vorgeschlagene Integrationsanwendungen
Die properties.chat-Methode ermöglicht verschiedene Integrationsarchitekturen für Teams und Tools:
Chat- und Collaboration-Bots für Unternehmen
Verknüpfen Sie Ihren Teamchat-Arbeitsbereich direkt mit Google Analytics.
- Threadsitzungen:Speichern Sie die
sessionIdanhand der Chat-Thread-ID, damit Teammitglieder gemeinsam Folgefragen stellen können. - Rendering von interaktiven Chat-Nachrichten:Formatieren Sie
table-Antwortblöcke in interaktive Karten-Widgets.
Autonome KI-Agenten und MCP-Tools (Model Context Protocol)
LLM-Orchestratoren wie Gemini, LangChain oder Claude mit einem GA-Analysetool ausstatten:
- 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 Faktualität und strukturierte Tabellen, die er in Empfehlungen für Multi-Channel-Marketing umwandelt.
Automatisierte Executive Briefings und Benachrichtigungen
Erstellen Sie geplante Dienste, die Anomalien proaktiv untersuchen:
- Ein täglicher Cron-Job fragt Folgendes 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 Skript automatisch eine Folgeabfrage aus, um die Ursachen zu ermitteln, und postet eine Zusammenfassung in internen Dashboards oder CRM-Systemen.