Программным способом с помощью функции "Спросить у советника" в Google Аналитике.

Метод chat Data API предоставляет программный доступ к Ask Advisor в Google Аналитике – аналитическому помощнику на основе ИИ, который помогает запрашивать, анализировать и диагностировать данные Google Аналитики с помощью естественного языка.

Хотя Ask Advisor доступен в интерактивном режиме в пользовательском интерфейсе Google Аналитики, API chat позволяет разработчикам, автономным ИИ-агентам и внутренним инструментам взаимодействовать с Ask Advisor программно по протоколу HTTP.

Важно! Этот продукт основан на ИИ-технологиях и может предлагать неточную информацию. Мы можем использовать историю ваших запросов в чате для улучшения продукта. Взаимодействие с продуктом регулируется нашими Условиями использования, Правилами использования ИИ и Политикой конфиденциальности.

Обзор

Метод chat позволяет задавать как разовые вопросы о данных, так и вести многошаговые диалоги:

  1. Запросы с одним ответом. Задавайте аналитические вопросы (например, "Какие каналы трафика были самыми популярными на прошлой неделе?") и получайте ответы на естественном языке вместе со структурированными таблицами данных.
  2. Многоэтапные разговоры. Передайте sessionId, чтобы сохранить историю разговора и задать уточняющие вопросы (например, "Почему в этот период снизился органический трафик?").
  3. Ответы со структурированными данными. Помимо текстовых ответов, ответы содержат структурированные блоки table с заголовками столбцов и строками.
  4. Мониторинг квоты чата. Проверьте оставшиеся квоты токенов чата в день и в час, задав для параметра returnPropertyQuota значение true.

Аутентификация

Для вызовов метода chat требуется авторизация OAuth 2.0 со следующей областью действия:

Подготовка

  1. Установите и инициализируйте gcloud CLI.

  2. Чтобы создать учетные данные приложения по умолчанию и предоставить аккаунту необходимые области действия, выполните следующие действия:

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

  3. В интерфейсе Google Аналитики предоставьте аккаунту пользователя доступ к ресурсу Google Аналитики.

  4. Настройте переменные среды, введя следующие команды: Замените PROJECT_ID идентификатором проекта, а PROPERTY_ID – идентификатором ресурса Google Аналитики. 

      export PROJECT_ID=PROJECT_ID
  export 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

Ask 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 – числовые значения с плавающей запятой.

Управление квотами Chat

Запросы Ask Advisor потребляют токены чата в зависимости от сложности запроса. Текущее состояние квоты возвращается в propertyQuota, когда returnPropertyQuota имеет значение true:

  • tokensPerDay – дневной лимит токенов и оставшийся баланс.
  • tokensPerHour – ограничение частоты запросов с использованием скользящего окна и оставшийся баланс.

Рекомендуемые приложения для интеграции

Метод properties.chat позволяет реализовать несколько архитектур интеграции для разных команд и инструментов:

Корпоративные чат-боты и боты для совместной работы

Подключите рабочую область чата команды напрямую к Google Аналитике.

  • Сессии с несколькими темами: Сохраняйте sessionId привязанный к идентификатору темы чата, чтобы участники команды могли задавать дополнительные вопросы совместно.
  • Отображение полезных подсказок. Форматирует table блоки ответов в интерактивные виджеты карточек.

Автономные ИИ-агенты и инструменты протокола контекста модели (MCP)

Оснастите оркестраторы LLM (например, Gemini, LangChain или Claude) аналитическим инструментом GA:

  • Вместо того чтобы заставлять LLM генерировать сложные запросы runReport, агент LLM может вызывать метод chat с намерением на естественном языке.
  • Агент получает высокоточные сводки и структурированные таблицы, на основе которых создает многоканальные маркетинговые рекомендации.

Автоматизированные отчеты для руководителей и оповещения

Создайте запланированные сервисы, которые будут заблаговременно выявлять аномалии:

  • Ежедневное задание cron: "Суммируй ключевые показатели эффективности за вчерашний день и определи, есть ли аномальное снижение конверсий".
  • Если скрипт обнаруживает аномалию, он автоматически запускает дополнительный запрос, чтобы определить ее причину, и публикует сводку на внутренних панелях управления или в CRM-системах.