Korzystanie z doradcy Analytics do wysyłania zapytań i analizowania danych

Metoda chat interfejsu Data API zapewnia automatyczny dostęp do doradcy Analytics – asystenta analitycznego opartego na AI, który pomaga zadawać pytania, analizować i diagnozować dane Google Analytics w języku naturalnym.

Doradca ds. Analytics jest dostępny interaktywnie w interfejsie Google Analytics, ale interfejs chat API umożliwia programistom, autonomicznym agentom AI i narzędziom wewnętrznym interakcję z Doradcą ds. Analytics programowo przez HTTP.

Ważne: ta usługa korzysta z AI i może wyświetlać nieprawidłowe informacje. Twoja aktywność na czacie może służyć do ulepszania usługi. Korzystanie z niej podlega Warunkom, Zasadom korzystania z AI oraz Polityce prywatności Google.

Przegląd

Metoda chat umożliwia zadawanie zarówno jednorazowych pytań dotyczących danych, jak i prowadzenie wieloetapowych sesji konwersacyjnych:

  1. Zapytania jednorazowe: zadawaj natychmiastowe pytania analityczne (np. „Jakie były nasze najpopularniejsze kanały ruchu w zeszłym tygodniu?”) i otrzymuj odpowiedzi w języku naturalnym wraz z tabelami danych strukturalnych.
  2. Rozmowy wieloetapowe: przekaż sessionId, aby zachować historię rozmowy i zadać dodatkowe pytania diagnostyczne (np. „Dlaczego w tym okresie spadł ruch bezpłatny?”).
  3. Odpowiedzi w formie danych strukturalnych: oprócz opisów tekstowych odpowiedzi zawierają uporządkowane table bloki z nagłówkami kolumn i wierszami.
  4. Monitorowanie limitu czatu: sprawdzaj pozostałe dzienne i godzinowe limity tokenów czatu, ustawiając returnPropertyQuota na true.

Uwierzytelnianie

Wywołania metody chat wymagają autoryzacji OAuth 2.0 z tym zakresem:

Zanim zaczniesz

  1. Zainstaluj i zainicjuj gcloud CLI.

  2. Aby wygenerować domyślne dane logowania aplikacji i przyznać kontu niezbędne zakresy, wykonaj to polecenie:

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"

  3. W interfejsie Google Analytics przyznaj swojemu kontu użytkownika dostęp do usługi w Google Analytics.

  4. Skonfiguruj zmienne środowiskowe, wpisując te wartości. Zastąp PROJECT_ID identyfikatorem projektu, a PROPERTY_ID – identyfikatorem usługi w Google Analytics. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

Przykład 1. Zapytanie jednoetapowe ze śledzeniem limitu

Aby rozpocząć nową rozmowę, utwórz ChatRequest zawierający userQuery. Ustaw returnPropertyQuota na true, aby sprawdzić pozostałe saldo tokenów.

Scenariusz: przychody i współczynnik konwersji według urządzenia

Chcesz porównać przychody i współczynnik konwersji w sesji na różnych urządzeniach w ciągu ostatnich 30 dni.

Żądanie 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
  }'

Odpowiedź HTTP

Odpowiedź zawiera:

  • Nowo przypisany sessionId, którego możesz użyć w kolejnych turach.
  • Lista blocks zawierająca podsumowanie w języku naturalnym (text) i tabelę strukturalną (table). Bloki tekstu mogą zawierać formatowanie Markdown, takie jak pogrubienie tekstu, nagłówki i linki.
  • Szczegóły propertyQuota obiektu.
{
  "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
    }
  }
}

Przykład 2. Diagnostyka konwersacyjna wieloetapowa

Aby zadać kolejne pytanie z zachowaniem kontekstu, w żądaniu uwzględnij parametr sessionId zwrócony w poprzedniej odpowiedzi.

Scenariusz: porównanie z poprzednim okresem

W nawiązaniu do poprzedniego porównania urządzeń prosisz doradcę o porównanie wyników z poprzednim okresem.

Żądanie 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."
  }'

Odpowiedź HTTP

Doradca Analytics korzysta z pamięci sesji, aby korelować wyniki z poprzednim okresem.

{
  "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%"
              }
            ]
          }
      }
    }
  ]
}

Struktura odpowiedzi i bloki danych

Obiekt ChatResponse zwraca komponenty strukturalne w tablicy blocks:

Typ bloku Pole Opis
Narrative Text blocks[].text Zrozumiałe dla człowieka wyjaśnienie i ogólne wnioski analityczne.
Tabela strukturalna blocks[].table Podział danych tabelarycznych zawierający headers (nazwy i typy danych) oraz rows (wartości komórek).

Typy danych w nagłówku tabeli

Kolumny w blocks[].table.headers opisują semantyczny typ danych:

  • string: wartości tekstowe kategorii (np. "desktop", "/shop/apparel").
  • float: liczby zmiennoprzecinkowe.

Zarządzanie limitami czatu

Żądania doradcy Analytics zużywają tokeny czatu w zależności od złożoności zapytania. Aktualny stan limitu jest zwracany w parametrze propertyQuota, gdy parametr returnPropertyQuota ma wartość true:

  • tokensPerDay: dzienny limit tokenów i pozostałe saldo.
  • tokensPerHour: limit szybkości w godzinowym oknie przesuwnym i pozostałe saldo.

Sugerowane aplikacje do integracji

Metoda properties.chat umożliwia korzystanie z różnych architektur integracji w zespołach i narzędziach:

Boty do czatu i współpracy w firmie

Połącz obszar roboczy czatu zespołowego bezpośrednio z Google Analytics.

  • Sesje wątkowe: zapisz sessionId w odniesieniu do identyfikatora wątku czatu, aby umożliwić członkom zespołu zadawanie dodatkowych pytań wspólnie.
  • Renderowanie karty informacyjnej: formatowanie bloków odpowiedzi table w interaktywne widżety kart.

Autonomiczne agenty AI i narzędzia protokołu Model Context Protocol (MCP)

Wyposaż orkiestratorów LLM (takich jak Gemini, LangChain czy Claude) w ogólnie dostępne narzędzie analityczne:

  • Zamiast zmuszać LLM do generowania złożonych zapytań runReport, agent LLM może wywoływać metodę chat z użyciem intencji w języku naturalnym.
  • Agent otrzymuje podsumowania o wysokiej zgodności z prawdą i tabele strukturalne, które wykorzystuje do tworzenia rekomendacji marketingu wielokanałowego.

Automatyczne podsumowania dla kadry kierowniczej i alerty

Twórz zaplanowane usługi, które aktywnie badają anomalie:

  • Codzienne zadanie crona wysyła zapytanie: „Podsumuj wczorajsze kluczowe dane o skuteczności i wskaż wszelkie nietypowe spadki liczby konwersji”.
  • Jeśli skrypt wykryje anomalię, automatycznie uruchomi kolejne zapytanie, aby zdiagnozować główne przyczyny problemu, a następnie opublikuje podsumowanie na wewnętrznych panelach lub w systemach CRM.