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 über die Google Analytics-Benutzeroberfläche verfügbar. Über die 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 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 Konversationssitzungen mit mehreren Antworten:
- Einzelne Anfragen:Sie können sofort analytische Fragen stellen, z. B. „Welche waren unsere wichtigsten Traffic-Channels in der letzten Woche?“, und erhalten Antworten in natürlicher Sprache sowie strukturierte Datentabellen.
- Unterhaltungen mit mehreren Runden:Ü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
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 zu gewähren:
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: Einzelrundenanfrage mit Kontingentverfolgung
Wenn Sie eine neue Unterhaltung starten möchten, erstellen Sie eine 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 Umsatz und Sitzung – Conversion-Rate für verschiedene Geräte 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 zugewiesenes
sessionId, das Sie für Folgezü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 setzen den vorherigen Gerätevergleich fort und 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
Bei „Ask Advisor“ wird der Sitzungsspeicher verwendet, 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 Objekt ChatResponse gibt strukturierte Komponenten im Array blocks 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 Ask Advisor-Anfragen werden Chat-Tokens basierend auf der Komplexität der Anfrage verbraucht.
Der aktuelle Kontingentstatus wird in propertyQuota zurückgegeben, wenn returnPropertyQuota den Wert true hat:
tokensPerDay: Das tägliche Tokenlimit und der verbleibende Betrag.tokensPerHour: Ratenbegrenzung für das stündliche gleitende Fenster und verbleibendes Guthaben.
Vorgeschlagene Integrationsanwendungen
Die properties.chat-Methode ermöglicht verschiedene Integrationsarchitekturen für Teams und Tools:
Enterprise-Chat- und Collaboration-Bots
Verknüpfen Sie Ihren Teamchat-Arbeitsbereich direkt mit Google Analytics.
- Sitzungen mit Threads:Speichern Sie
sessionIdanhand der Chat-Thread-ID, damit Teammitglieder gemeinsam Folgefragen stellen können. - Rendering von interaktiven Chat-Nachrichten:Formatieren Sie
table-Antwortblöcke als 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 das Multi-Channel-Marketing umwandelt.
Automatisierte Executive Briefings und Benachrichtigungen
Erstellen Sie geplante Dienste, die Anomalien proaktiv untersuchen:
- Ein täglicher Cron-Job fragt: 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.