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

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

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

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

Обзор

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

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

Тип блокировки Поле Описание
Narrative Text 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 в интерактивные виджеты карточек.

Автономные ИИ-агенты и инструменты Model Context Protocol (MCP)

Предоставьте оркестраторам LLM (таким как Gemini, LangChain или Claude) доступ к аналитическому инструменту GA:

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

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

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

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

Дальнейшие действия