Programowe korzystanie z usługi Ask Advisor w Google Analytics do wykonywania zapytań i analizowania danych

Metoda chat interfejsu Data API umożliwia automatyczny dostęp do Ask Advisor w Google Analytics – asystenta analitycznego opartego na AI, który pomaga zadawać pytania, analizować i diagnozować dane Google Analytics za pomocą języka naturalnego.

Narzędzie Ask Advisor jest dostępne interaktywnie w interfejsie Google Analytics użytkownika, ale interfejs chat API umożliwia deweloperom, autonomicznym agentom AI i narzędziom wewnętrznym interakcję z narzędziem Ask Advisor automatycznie przez HTTP.

Uwaga: Metoda chat jest dostępna w wersji v1alpha interfejsu Data API.

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 korzystania z usługi, Zasadom korzystania z AI oraz Polityce prywatności Google.

Przegląd

Metoda chat umożliwia zadawanie zarówno jednorazowych pytań ad hoc, jak i prowadzenie sesji konwersacyjnych składających się z wielu tur:

1. Zapytania jednorazowe: zadawaj natychmiastowe pytania analityczne (np. „Jakie były nasze główne kanały ruchu w zeszłym tygodniu?”) i otrzymuj odpowiedzi w języku naturalnym wraz z tabelami danych uporządkowanych.
2. Rozmowy wieloturowe: przekaż sessionId aby zachować historię rozmowy i zadawać dodatkowe pytania diagnostyczne (np. „Dlaczego w tym okresie spadł ruch bezpłatny?”).
3. Odpowiedzi z danymi uporządkowanymi: oprócz opisów tekstowych odpowiedzi zawierają uporządkowane table bloki z nagłówkami kolumn i wierszami.
4. Monitorowanie limitów czatu: sprawdzaj pozostałe limity tokenów czatu na dzień i na godzinę quotas by setting returnPropertyQuota to true.

Uwierzytelnianie

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

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

Uwaga: ten zakres różni się od zakresu wymaganego w przypadku standardowych metod raportowania (np. runReport).

Zanim zaczniesz

Wskazówka: aby wypróbować metodę chat interaktywnie w Pythonie bez konfigurowania środowiska lokalnego, otwórz notatnik Colab Ask Advisor.

1. Zainstaluj i zainicjuj gcloud CLI.

2. Aby wygenerować domyślne dane logowania aplikacji i przyznać kontu niezbędne zakresy, uruchom 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 informacje. 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 jednorazowe ze śledzeniem limitów

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.
• Listę blocks zawierającą zarówno podsumowanie w języku naturalnym (text) jak i tabelę uporządkowaną (table). Bloki tekstowe mogą zawierać formatowanie Markdown, takie jak pogrubienie tekstu, nagłówki i linki.
• Szczegóły propertyQuota usługi.

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

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

Scenariusz: porównanie z poprzednim okresem

Po poprzednim porównaniu urządzeń poproś narzędzie Ask Advisor 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

Narzędzie Ask Advisor używa pamięci sesji, aby powiązać 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 uporządkowane komponenty w tablicy blocks:

Typ bloku	Pole	Opis
Tekst narracyjny	blocks[].text	Wyjaśnienie zrozumiałe dla człowieka i najważniejsze wnioski analityczne.
Tabela uporządkowana	blocks[].table	Zestawienie danych w formie tabeli zawierające 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 Ask Advisor zużywają tokeny czatu w zależności od złożoności zapytania. Aktualny stan limitu jest zwracany w propertyQuota gdy returnPropertyQuota ma wartość true:

• tokensPerDay: dzienny limit tokenów i pozostałe saldo.
• tokensPerHour: godzinne ograniczanie liczby żądań w oknie przesuwnym i pozostałe saldo.

Sugerowane aplikacje integracyjne

Metoda properties.chat odblokowuje kilka architektur integracji w różnych zespołach i narzędziach:

Boty do czatu i współpracy w firmie

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

• Sesje w wątkach: zapisuj sessionId w powiązaniu z identyfikatorem wątku czatu, aby umożliwić członkom zespołu wspólne zadawanie dodatkowych pytań.
• Renderowanie kart informacyjnych: formatuj bloki odpowiedzi table w interaktywne widżety kart.

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

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

• Zamiast zmuszać LLM do generowania złożonych runReport zapytań, agent LLM może wywoływać metodę chat z intencją w języku naturalnym.
• Agent otrzymuje podsumowania o wysokiej zgodności z prawdą i tabele uporządkowane, które może syntetyzować w rekomendacje marketingu wielokanałowego.

Automatyczne podsumowania dla kierownictwa i alerty

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

• Codzienne zadanie crona wysyła zapytanie: "Podsumuj wczorajsze kluczowe wskaźniki skuteczności i zidentyfikuj wszelkie anomalne spadki konwersji."
• Jeśli zostanie wykryta anomalia, skrypt automatycznie wywoła dodatkowe zapytanie, aby zdiagnozować główne przyczyny, i opublikuje podsumowanie w wewnętrznych panelach lub systemach CRM.

Dalsze kroki

• Wypróbuj interaktywny notatnik Colab Ask Advisor, aby uruchamiać zapytania jednorazowe i wieloturowe za pomocą biblioteki klienta Python.
• Zapoznaj się z dokumentacją interfejsu REST API properties.chat.
• Dowiedz się więcej o limitach interfejsu Data API.