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:
- 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.
- Rozmowy wieloetapowe: przekaż
sessionId, aby zachować historię rozmowy i zadać dodatkowe pytania diagnostyczne (np. „Dlaczego w tym okresie spadł ruch bezpłatny?”). - Odpowiedzi w formie danych strukturalnych: oprócz opisów tekstowych odpowiedzi zawierają uporządkowane
tablebloki z nagłówkami kolumn i wierszami. - Monitorowanie limitu czatu: sprawdzaj pozostałe dzienne i godzinowe limity tokenów czatu, ustawiając
returnPropertyQuotanatrue.
Uwierzytelnianie
Wywołania metody chat wymagają autoryzacji OAuth 2.0 z tym zakresem:
Zanim zaczniesz
Zainstaluj i zainicjuj gcloud CLI.
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"W interfejsie Google Analytics przyznaj swojemu kontu użytkownika dostęp do usługi w Google Analytics.
Skonfiguruj zmienne środowiskowe, wpisując te wartości. Zastąp
PROJECT_IDidentyfikatorem projektu, aPROPERTY_ID– identyfikatorem usługi w Google Analytics.export PROJECT_ID=
PROJECT_IDexport 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
blockszawierają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
propertyQuotaobiektu.
{
"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
sessionIdw 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
tablew 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ęchatz 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.