Daten programmatisch mit „Ask Advisor“ in Google Analytics abfragen und analysieren

Die chat-Methode der Data API bietet programmatischen Zugriff auf Ask Advisor in Google Analytics – ein KI-gestützter Analytics-Assistent, mit dem Sie Ihre Google Analytics-Daten in natürlicher Sprache abfragen, analysieren und diagnostizieren können.

„Frag den Berater“ ist zwar interaktiv in der Google Analytics Benutzeroberfläche verfügbar, aber mit der chat API können Entwickler, autonome KI-Agenten und interne Tools programmatisch über HTTP mit „Frag den Berater“ interagieren.

**Hinweis**: Die chat-Methode ist in der v1alpha-Version der Data API verfügbar.

Wichtig: Für dieses Produkt wird künstliche Intelligenz verwendet. Informationen können daher unter Umständen fehlerhaft sein. Ihre Chat Aktivitäten können zur Verbesserung des Produkts verwendet werden. Ihre Nutzung des Produkts unterliegt den Google-Nutzungsbedingungen, der Richtlinie zur Nutzung von KI und der Datenschutzerklärung von Google.

Übersicht

Mit der chat-Methode sind sowohl einmalige Ad-hoc-Datenfragen als auch mehrfache Unterhaltungssitzungen möglich:

1. Einmalige Abfragen:Stellen Sie sofort analytische Fragen (z. B. „Was waren unsere wichtigsten Traffic-Channels in der letzten Woche?“) und erhalten Sie Antworten in natürlicher Sprache sowie strukturierte Datentabellen.
2. Mehrfache Unterhaltungen: Ü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?“).
3. Antworten mit strukturierten Daten:Neben Texten enthalten die Antworten strukturierte table Blöcke mit Spaltenüberschriften und Zeilen.
4. Überwachung des Chatkontingents:Sie können die verbleibenden täglichen und stündlichen Kontingente für Chat-Tokens prüfen, indem Sie returnPropertyQuota auf true setzen.

Authentifizierung

Für Aufrufe der chat-Methode ist eine OAuth 2.0-Autorisierung mit dem folgenden Bereich erforderlich:

• https://www.googleapis.com/auth/analytics.chatbot.read

Hinweis: Dieser Bereich unterscheidet sich von dem Bereich, der für Standardberichtsmethoden (z. B. runReport) erforderlich ist.

Hinweis

**Tipp**: Wenn Sie die chat-Methode interaktiv in Python testen möchten, ohne eine lokale Umgebung einzurichten, öffnen Sie das Ask Advisor Colab-Notebook.

1. Installieren und initialisieren Sie die gcloud CLI.

2. Führen Sie den folgenden Befehl aus, um Application Default Credentials 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"
   

3. Gewähren Sie Ihrem Nutzerkonto in der Google Analytics-Benutzeroberfläche Zugriff auf eine Google Analytics-Property.

4. Konfigurieren Sie Umgebungsvariablen. Dazu geben Sie Folgendes ein. Ersetzen Sie PROJECT_ID durch die ID Ihres Projekts und PROPERTY_ID durch die ID Ihrer Google Analytics-Property.

     export PROJECT_ID=PROJECT_ID
     export PROPERTY_ID=PROPERTY_ID

Beispiel 1: Einmalige Abfrage mit Kontingent-Tracking

Erstellen Sie eine ChatRequest mit Ihrer userQuery, um eine neue Unterhaltung zu starten. 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:

• Eine neu zugewiesene sessionId die Sie für weitere Unterhaltungen verwenden können.
• Eine Liste von blocks die sowohl eine Zusammenfassung in natürlicher Sprache (text) als auch eine strukturierte Tabelle (table) enthalten. Textblöcke können Markdown-Formatierungen wie fettgedruckten Text, Überschriften und Links enthalten.
• Die Details zu propertyQuota der Property.

{
  "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: Mehrfache Unterhaltung zur Diagnose

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: Vergleich mit dem vorherigen Zeitraum

Nach dem vorherigen Gerätevergleich bitten Sie den Berater, 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

„Frag den Berater“ verwendet den Sitzungsspeicher, um die Ergebnisse mit dem vorherigen Zeitraum zu vergleichen.

{
  "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:

Block-Typ	Feld	Beschreibung
Text	blocks[].text	Eine menschenlesbare Erklärung und wichtige analytische Erkenntnisse.
Strukturierte Tabelle	blocks[].table	Tabellarische Datenaufschlüsselung 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.

Verwaltung des Chatkontingents

Bei Anfragen an Ask Advisor werden Chat-Tokens basierend auf der Komplexität der Abfrage verbraucht. Der aktuelle Kontingentstatus wird in propertyQuota zurückgegeben, wenn returnPropertyQuota auf true gesetzt ist:

• tokensPerDay: Tägliches Token-Limit und verbleibendes Guthaben.
• tokensPerHour: Stündliches gleitendes Ratenlimit und verbleibendes Guthaben.

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 Team-Chat-Arbeitsbereich direkt mit Google Analytics.

• Threadsitzungen: Speichern Sie die sessionId für die Chat-Thread-ID, damit Teammitglieder gemeinsam Folgefragen stellen können.
• Rendering interaktiver Chat-Nachrichten:Formatieren Sie table Antwortblöcke in interaktive Chat-Nachrichten.

Autonome KI-Agenten und MCP-Tools (Model Context Protocol)

Stellen Sie LLM-Orchestratoren (z. B. Gemini, LangChain oder Claude) ein GA-Analysetool zur Verfügung:

• Anstatt ein LLM zu zwingen, komplexe runReport Abfragen zu generieren, kann der LLM-Agent die chat Methode mit einer Absicht in natürlicher Sprache aufrufen.
• Der Agent erhält Zusammenfassungen mit hoher Faktizität und strukturierte Tabellen, die er zu Empfehlungen für das Multi-Channel-Marketing zusammenfassen kann.

Automatisierte Briefings und Benachrichtigungen für Führungskräfte

Erstellen Sie geplante Dienste, die Anomalien proaktiv untersuchen:

• Ein täglicher Cronjob führt die folgende Abfrage aus: „Fassen Sie die wichtigsten Leistungsmesswerte von gestern zusammen und ermitteln Sie 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.

Nächste Schritte

• Testen Sie das interaktive Colab-Notebook „Ask Advisor“, um einmalige und Mehrfachdialoge mit der Python-Clientbibliothek auszuführen.
• Lesen Sie die properties.chat REST API Referenz.
• Weitere Informationen zu Kontingenten und Limits der Data API