google-analytics-data-api-basics

google-analytics-data-api-basics — официальный workflow Google для программного доступа к отчётам Google Analytics Data API v1beta. Он предназначен для случаев, когда нужно обращаться к свойствам Google Analytics, строить настраиваемые отчёты, автоматизировать выгрузки, выбирать метрики и измерения или заранее проверять, совместимы ли выбранные поля. Источник отдельно предупреждает, что этот навык не предназначен для операций Google Analytics Admin API, например создания свойств и управления пользователями, и не заменяет установку фронтенд-трекинга. Такое ограничение помогает не смешивать получение отчётных данных с администрированием Analytics и внедрением счётчика. Перед первым запросом workflow предлагает включить Analytics Data API в нужном Google Cloud project командой gcloud services enable analyticsdata.googleapis.com --quiet. Затем доступность API проверяется через gcloud services list --enabled с фильтром analyticsdata.googleapis.com. Это не формальность: без включённого API у проекта не будет нужной квоты и разрешений для выполнения отчётов. Для аутентификации источник указывает Application Default Credentials и команду gcloud auth application-default login со scope cloud-platform и analytics.readonly. Поэтому перед запуском нужно проверить, что используется ожидаемый аккаунт, есть доступ к целевому свойству и выбран правильный Cloud project; сам skill не угадывает property ID и не выдаёт доступ автоматически. Для клиентского кода доступны официальные библиотеки Python, Java, PHP, Node.js, .NET, Go и Ruby, а для конкретного языка исходник направляет к отдельному reference-файлу. Python quick start устанавливает пакет google-analytics-data и создаёт BetaAnalyticsDataClient. Запрос строится через RunReportRequest: в property передаётся идентификатор в формате properties/<PROPERTY_ID>, затем задаются dimensions, metrics и date_ranges. Пример группирует activeUsers и sessions по city и date, печатает значения строк отчёта и использует DateRange с датой начала и today. Это полезный минимальный сценарий для отчёта по географии и динамике, но фактический property ID и даты должны быть предоставлены проектом. Навык объясняет различие между измерениями и метриками. В качестве измерений перечислены city, country, date в формате YYYYMMDD, deviceCategory с вариантами desktop, mobile и tablet, eventName и pageTitle. В качестве количественных полей указаны activeUsers, eventCount, sessions, screenPageViews и totalRevenue, включая доход от покупок, подписок и рекламы. Полный список полей нужно брать из официальной схемы Data API, а не расширять по догадке. Такой набор подходит для отчётов по пользователям, событиям, сессиям, просмотрам страниц, устройствам, страницам и выручке, если выбранная Analytics property действительно возвращает нужные данные. Отдельный важный сценарий — проверка совместимости dimensions и metrics до запуска дорогого или повторяемого отчёта. Если API возвращает INVALID_ARGUMENT из-за несовместимых полей, источник предлагает получить метаданные через getMetadata() и вызвать checkCompatibility() с конкретным набором Dimension и Metric. В Python-примере проверяются itemName и date вместе с activeUsers и totalRevenue, после чего ответ сопоставляется с enum Compatibility. Это позволяет разделить ошибку схемы запроса и ошибку доступа: сначала нужно удостовериться, что API включён и credentials действительны, а затем подтвердить, что комбинация полей разрешена. Практический маршрут выглядит так: определить Cloud project и Analytics property, включить API, проверить его состояние, настроить ADC с read-only scope, выбрать клиентскую библиотеку, прочитать reference для нужного языка, собрать RunReportRequest и отдельно проверить совместимость полей. Ограничения источника существенны: API-имена должны соответствовать официальной схеме, данные зависят от доступа к конкретной property, а пример не обещает одинаковый ответ для всех аккаунтов. Навык помогает подготовить воспроизводимый отчёт и диагностировать несовместимые поля, но не создаёт свойство, не меняет настройки Analytics и не подтверждает наличие данных без фактического запроса.