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

Metoda chat interfejsu Data API zapewnia zautomatyzowany dostęp do funkcji Ask Advisor w Google Analytics – opartego na AI asystenta analitycznego, który pomaga wysyłać zapytania, analizować i diagnozować dane Google Analytics za pomocą języka naturalnego.

Chociaż usługa Ask Advisor jest dostępna interaktywnie w interfejsie Google Analytics, interfejs API chat umożliwia deweloperom, autonomicznym agentom AI i narzędziom wewnętrznym interakcję z nią automatycznie 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 korzystania z usługi, Zasadom korzystania z AI oraz Polityce prywatności Google.

Przegląd

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

  1. Zapytania jednoetapowe: 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 uporządkowanych danych.
  2. Rozmowy wieloetapowe: przekazuj sessionId, aby zachować historię rozmowy i zadawać dodatkowe pytania diagnostyczne (np. „Dlaczego w tym okresie spadł ruch bezpłatny?”).
  3. Odpowiedzi z uporządkowanymi danymi: oprócz tekstu odpowiedzi zawierają uporządkowane bloki table z nagłówkami kolumn i wierszami.
  4. Monitorowanie limitów czatu: sprawdź 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 uwierzytelnianie 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 polecenia. 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 obiekt 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żywać w kolejnych turach.
  • Lista obiektów blocks zawierająca zarówno podsumowanie w języku naturalnym (text), jak i tabelę strukturalną (table). Bloki tekstu mogą zawierać formatowanie Markdown, takie jak pogrubiony tekst, 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 wieloetapowa

Aby zadać dodatkowe pytanie z zachowaniem kontekstu, dołącz do żądania 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

Ask Advisor używa pamięci sesji, aby skorelować 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 blokowania Pole Opis
Narrative Text blocks[].text Zrozumiałe dla człowieka wyjaśnienie i ogólne 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: kategorialne wartości tekstowe (np. "desktop", "/shop/apparel").
  • float: liczby zmiennoprzecinkowe.

Zarządzanie limitami w Google Chat

Prośby do Ask Advisor zużywają tokeny czatu w zależności od złożoności zapytania. Bieżący stan limitu jest zwracany w propertyQuota, gdy returnPropertyQuota ma wartość true:

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

Sugerowane aplikacje do integracji

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

Boty do czatów i współpracy w przedsiębiorstwach

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

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

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

Wyposaż orkiestratory LLM (takie jak Gemini, LangChain czy Claude) w narzędzie analityczne GA:

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

Automatyczne podsumowania i alerty dla kadry kierowniczej

Tworzenie zaplanowanych usług, które proaktywnie badają anomalie:

  • Codzienne zadanie crona wysyła zapytanie: „Podsumuj najważniejsze wskaźniki skuteczności z wczoraj i zidentyfikuj wszelkie nietypowe spadki liczby konwersji”.
  • Jeśli zostanie wykryta anomalia, skrypt automatycznie uruchamia zapytanie uzupełniające, aby zdiagnozować główne przyczyny, i publikuje podsumowanie w wewnętrznych panelach lub systemach CRM.

Dalsze kroki