Метод chat в рамках API данных обеспечивает программный доступ к Analytics Advisor — аналитическому помощнику на основе искусственного интеллекта, который помогает запрашивать, анализировать и диагностировать данные Google Analytics с помощью естественного языка.
Хотя Analytics Advisor доступен в интерактивном режиме в пользовательском интерфейсе Google Analytics, API chat позволяет разработчикам, автономным агентам ИИ и внутренним инструментам взаимодействовать с Analytics Advisor программно по протоколу HTTP.
Важно: Этот продукт использует искусственный интеллект и может отображать неточную информацию. Ваша активность в чате может быть использована для улучшения продукта, и ваше использование регулируется Условиями использования Google, Политикой использования ИИ и Политикой конфиденциальности .
Обзор
Метод chat позволяет задавать как разовые вопросы с произвольным ответом, так и вести многоэтапные диалоги:
- Запросы в один цикл: Задавайте мгновенные аналитические вопросы (например, «Какие каналы трафика были у нас самыми популярными на прошлой неделе?») и получайте ответы на естественном языке вместе со структурированными таблицами данных.
- Многоэтапные диалоги: передайте
sessionId, чтобы сохранить историю переписки и задать уточняющие диагностические вопросы (например, «Почему органический трафик снизился за этот период?»). - Ответы в виде структурированных данных: помимо текстовых описаний, ответы содержат структурированные
tableблоки с заголовками столбцов и строками. - Мониторинг квот чата: Чтобы проверить оставшиеся квоты токенов чата на день и час, установите параметр
returnPropertyQuotaвtrue.
Аутентификация
Для обращения к методу chat требуется авторизация OAuth 2.0 со следующими областями действия:
Прежде чем начать
Установите и инициализируйте интерфейс командной строки gcloud.
Чтобы сгенерировать учетные данные приложения по умолчанию и предоставить вашей учетной записи необходимые права доступа, выполните следующую команду:
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"В пользовательском интерфейсе Google Analytics предоставьте учетной записи пользователя доступ к ресурсу Google Analytics .
Настройте переменные среды, введя следующее. Замените
PROJECT_IDна идентификатор вашего проекта. project иPROPERTY_ID, указав идентификатор вашего ресурса Google Analytics.export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
Пример 1: Одноэтапный запрос с отслеживанием квоты.
Чтобы начать новый диалог, создайте объект ChatRequest , содержащий ваш userQuery . Установите returnPropertyQuota в true , чтобы проверить оставшийся баланс токенов.
Сценарий: Доходы и коэффициент конверсии по устройствам
Вы хотите сравнить выручку и коэффициент конверсии сессий на разных устройствах за последние 30 дней.
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
}'
HTTP-ответ
В ответе содержится:
- Новый идентификатор
sessionId, который можно использовать для последующих реплик. - Список
blocks, содержащих как текстовое резюме на естественном языке (text), так и структурированную таблицу (table). Текстовые блоки могут содержать форматирование Markdown, например, жирный текст, заголовки и ссылки. - Подробная информация об объекте недвижимости
propertyQuota).
{
"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
}
}
}
Пример 2: Многоэтапная диагностика разговора
Чтобы задать уточняющий вопрос, сохранив при этом контекст, включите в свой запрос идентификатор sessionId , полученный из предыдущего ответа.
Сценарий: Сравните с предыдущим периодом.
В продолжение предыдущего сравнения устройств, вы просите консультанта сравнить результаты с предыдущим периодом.
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."
}'
HTTP-ответ
Analytics Advisor использует память сессии для сопоставления результатов с предыдущим периодом.
{
"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%"
}
]
}
}
}
]
}
Структура ответа и блоки данных
Объект ChatResponse возвращает структурированные компоненты в массиве blocks :
| Тип блока | Поле | Описание |
|---|---|---|
| Повествовательный текст | blocks[].text | Понятное для человека объяснение и основные аналитические выводы. |
| Структурированная таблица | blocks[].table | Табличная структура данных, содержащая headers (названия и типы данных) и rows (значения ячеек). |
Типы данных заголовка таблицы
Столбцы в blocks[].table.headers описывают семантический тип данных:
-
string: Категориальные текстовые значения (например,"desktop","/shop/apparel"). -
float: Числовые значения с плавающей запятой.
Управление квотами чата
Запросы Analytics Advisor расходуют токены чата в зависимости от сложности запроса. Текущее состояние квоты возвращается в propertyQuota , когда returnPropertyQuota равно true :
-
tokensPerDay: Суточный лимит токенов и остаток на счету. -
tokensPerHour: Почасовой лимит скользящего окна и остаток средств.
Рекомендуемые приложения для интеграции
Метод properties.chat открывает доступ к нескольким архитектурам интеграции между командами и инструментами:
Корпоративные чат-боты и боты для совместной работы
Подключите рабочее пространство командного чата напрямую к Google Analytics.
- Вложенные сессии: Сохраняйте идентификатор
sessionIdв соответствии с идентификатором ветки чата, чтобы участники команды могли совместно задавать уточняющие вопросы. - Расширенная визуализация карточек: преобразование блоков ответов
tableв интерактивные виджеты-карточки.
Инструменты для автономных агентов искусственного интеллекта и протокола контекста модели (MCP)
Оснастите системы управления обучением на уровне магистратуры (LLM) (такие как Gemini, LangChain или Claude) аналитическим инструментом GA:
- Вместо того чтобы заставлять LLM генерировать сложные запросы
runReport, агент LLM может вызывать методchatс использованием намерений на естественном языке. - Агент получает подробные сводки и структурированные таблицы для синтеза в многоканальные маркетинговые рекомендации.
Автоматизированные брифинги для руководителей и оповещения
Создайте запланированные службы, которые будут заблаговременно исследовать аномалии:
- Ежедневное задание cron запрашивает: «Подвести итоги ключевых показателей эффективности за вчерашний день и выявить любое аномальное снижение конверсий».
- В случае обнаружения аномалии скрипт автоматически запускает последующий запрос для выявления первопричин и публикует сводную информацию на внутренних панелях мониторинга или в CRM-системах.