Начало работы с Google Analytics Data API (GA4). Ваш первый запрос

С помощью этого руководства вы сможете создать свой первый запрос к Google Analytics Data API (GA4) и написать первую программу на Python с нулевыми или базовыми знаниями в программировании. И в этом вам помогут - клиентская библиотека, браузер и Google Colab.

В предыдущей статье вы познакомились с возможностями Data API, Admin API, доступными методами и квотами в GA4. Теперь пришло время выполнить свой первый запрос на языке Python.

Почему Python?

Python - это язык программирования, который широко используется в интернет-приложениях, разработке программного обеспечения, науке о данных и машинном обучении (ML). Разработчики используют Python, потому что он эффективен, прост в изучении и работает на разных платформах. Программы на языке Python можно скачать бесплатно, они совместимы со всеми типами систем и повышают скорость разработки.

Язык Python имеет множество преимуществ:

• разработчики могут легко читать и понимать программы на Python, поскольку язык имеет базовый синтаксис, похожий на синтаксис английского;
• Python помогает разработчикам быть более продуктивными, поскольку они могут писать программы на Python, используя меньше строк кода, чем в других языках;
• Python имеет большую стандартную библиотеку, содержащую многократно используемые коды практически для любой задачи. В результате разработчикам не требуется писать код с нуля;
• разработчики могут легко сочетать Python с другими популярными языками программирования: Java, C и C++
• активное сообщество Python состоит из миллионов поддерживающих разработчиков со всего мира. При возникновении проблем сообщество поможет в их решении;
• кроме того, в Интернете доступно множество полезных ресурсов для изучения Python. Например, вы можете легко найти видеоролики, учебные пособия, документацию и руководства для разработчиков;
• Python можно переносить на различные операционные системы: Windows, macOS, Linux и Unix;
• в официальной документации Яндекса и Google представлены примеры кода на разных языках, одним из которых является Python.

Одним из направлений, в котором используется Python как язык №1 – это наука о данных (data science) и машинное обучение (machine learning, ML). Наука о данных извлекает ценную информацию из данных, а машинное обучение позволяет компьютерам автоматически учиться на данных и делать точные прогнозы. Специалисты по работе с данными используют Python для решения следующих задач:

• исправление и удаление неверных данных (очистка данных);
• извлечение и выбор различных характеристик данных;
• разметка данных добавляет данным значимые имена;
• поиск статистической информации в данных;
• визуализация данных с помощью диаграмм и графиков: линейных диаграмм, столбчатых диаграмм, гистограмм и круговых диаграмм.

Для работы инженера данных, аналитика данных и BI-разработчика, а также ETL-процессов в Python имеется большое количество библиотек, существенно упрощающих написание своей программы. Для Google Analytics 4 тоже существует клиентская библиотека, которую вы будете использовать при создании своего первого запроса.

Примечание: в моем блоге есть материал по прогнозированию SEO-трафика Google Analytics 4 с помощью Python и Prophet. Если вам интересна данная тема, то можете ознакомиться с публикацией здесь.

Существуют две часто используемые версии языка Python - Python 2 и Python 3. Эти версии похожи, но есть отличия, из-за которых они не являются совместимыми - программы, написанные на одной версии языка, могут не работать в другой. Рекомендуется использовать версию Python 3 и выше, желательно >= 3.5 (сейчас уже есть версия 3.12).

Google Colab

Чтобы работать с API аналитических систем и выполнять запросы на Python, необходимо использовать специальное программное обеспечение (ПО). Такое ПО называют интегрированной средой разработки (IDE). Наиболее популярным Python IDE является PyCharm. Еще очень распространена IDE Spyder и JupyterLab.

Многие интернет-маркетологи и аналитики данных в своей работе так же используют блокнот Jupyter Notebook, который можно установить с помощью дистрибутива Anaconda, включающий набор популярных библиотек для работы с данными, таких как: NumPy, SciPy, Astropy и др. Еще есть Visual Studio Code и много других продуктов.

Как вы понимаете, выбор тех или иных программ зависит исключительно от ваших предпочтений в изучении или от тех инструментов, которые используются в вашей компании. Однако для работы с API Google Analytics 4 я предлагаю использовать другой сервис - Google Colab.

Colaboratory (или просто Colab) - это бесплатный продукт Google Research. Он позволяет любому человеку писать и выполнять код Python прямо в браузере, без установки каких-либо программ и без дополнительной настройки. По сути, Colab - это размещенная на хостинге служба Jupyter Notebook, которая предоставляет доступ к своим вычислительным ресурсам, включая графические процессоры, благодаря которым можно заниматься не только базовой аналитикой данных, но и более сложными исследованиями в области машинного обучения. Google в Colab поддерживает актуальное состояние библиотек и их взаимную работу. Ваши проекты сохраняются не локально на компьютере, а на Google Диске. Они также могут быть загружены с GitHub. Таким образом, вы можете легко работать над одним проектом с другими людьми и делиться файлами со своей командой. Colab - отличное решение для начинающих пользователей, студентов, специалистов по обработке данных и исследователей в области искусственного интеллекта.

Небольшое демонстрационное видео о работе в Colab:

Браузер, клиентская библиотека на Python, Colab - это все ваши инструменты, которые вы будете использовать, создавая первый запрос к API Google Analytics GA4.

Начало работы

Как вы уже знаете, Google разделяет API в соответствии с их функциональным значением. Есть API управления и API отчетов. В отличие от старой версии Google Analytics (Universal Analytics, GA3), где можно было использовать такие API, как: Google Analytics Reporting API v4, Google Analytics Reporting API v3, Management API, Multi-Channel Funnels, Real-time Reporting, Metadata API, User Deletion API, в новом Google Analytics 4 используется два API:

1. Data API
2. Admin API

Google Analytics Data API предоставляет вам программный доступ к данным отчетов Google Analytics 4 (GA4). Он помогает понять, как люди используют ваше веб-приложение, приложение для iOS или Android. Data API можно использовать только для доступа к ресурсам Google Analytics 4, и он несовместим с Universal Analytics. Именно с Data API вы будете работать 99% времени. И в этом руководстве мы будем использовать именно его.

Примечание: на момент выхода данного руководства API Google Analytics 4 находятся в бета- и альфа-стадиях. Это означает, что какой-то функционал может измениться кардинально, а какой-то незначительно

Примечание: если вы хотите научиться работать с API Google Analytics 4 на языке R и знаете английский язык, то можете использовать материалы Марка Эдмондсона (Mark Edmondson). Для русскоязычной аудитории очень хорошо освещает R для интернет-маркетинга Алексей Селезнёв.

Самый простой способ начать работу с API Google Analytics 4 - это загрузить одну из клиентских библиотек (Java, PHP, Python, Node.js, Ruby, Go, .NET). Для получения фактических данных Google Analytics 4 в Data API существуют различные методы: runReport, batchRunReports, runPivotReport, batchRunPivotReports, getMetadata, runRealtimeReport, runFunnelReport. Первый запрос, который вы создадите, будет связан с методом runReport - получение одного отчета с данными о ваших событиях GA4.

Google предоставляет возможность из браузера запустить каждый метод прямо в официальной справке разработчика. Например, если вы перейдете на страницу метода runReport, то справа увидите кнопку Попробовать:

Нажав на нее, вам откроется отдельная панель с некоторыми настройками. Вы можете раскрыть конструктор запроса на весь экран с помощью соответствующей иконки:

Тогда вы сможете полноценно работать с редактором:

Добавив все необходимые значения в тело запроса и нажав кнопку Execute, вы получите результат прямо в этой вкладке:

Код ответа 200 означает, что запрос был выполнен успешно. Однако без первоначальных знаний о теле запроса, его структуре, списке передаваемых полей и областях авторизации вам будет сложно сформировать свой первый запрос и протестировать его. Именно поэтому я предлагаю использовать готовую библиотеку на Python, а также быстрый запуск API из документации Google. Таким образом, последовательность действий по выгрузке данных из Google Analytics 4 с помощью API сводится к нескольким простым шагам:

1. создание проекта в Colab;
2. быстрый запуск API через официальную документацию Google;
3. добавление сервисного аккаунта в ресурс Google Analytics 4;
4. загрузка приватного ключа в Google Диск;
5. написание первого запроса / настройка аутентификации;
6. сравнение интерфейсных данных и Data API.

Рассмотрим каждый шаг подробнее.

1. Создание проекта в Colab

Чтобы создать свой первый проект в Colab, авторизуйтесь в своей учетной записи Gmail и перейдите по ссылке. Вам откроется приветственное окно и ваши проекты:

Если вы никогда раньше не работали с Colaboratory, то никаких проектов, кроме демонстрационного, в списке вы не увидите. Для создания первого проекта нажмите на Создать блокнот:

В новом окне вы увидите только что созданный блокнот, в котором вы будете писать код программы на Python. При желании вы можете переименовать свой проект, задав ему понятное название, например - API Google Analytics 4. Первый запрос:

На этом первый шаг завершен. Оставьте вкладку с вашим проектом Colab открытой и переходите к следующему этапу.

2. Быстрый запуск API

Начинающим пользователям Google предоставляет возможность быстро начать работу с API Google Analytics, перейдя в официальную документацию разработчиков. Сделайте это, а затем на открывшейся вкладке нажмите на синюю кнопку Enable the Google Analytics Data API v1:

Это действие автоматически создаст вам новый проект в Google Cloud Platform (GCP), а также активирует Google Analytics Data API v1 и создаст учетную запись службы, необходимую для дальнейшего создания запросов. Для работы с Data API платежный аккаунт в Google Cloud не требуется, поэтому вы можете использовать любую учетную запись Gmail.

Нажав на кнопку, введите имя проекта (Enter new project name). Например, API GA4:

В завершение нажмите NEXT (Далее). Начнется автоматическое создание проекта. Через некоторое время Google выдаст вам уведомление об успешной настройке проекта и создании учетной записи службы:

Скачайте к себе на компьютер приватный ключ, нажав на кнопку DOWNLOAD PRIVATE KEY AS JSON. Его вы будете использовать для аутентификации своей учетной записи службы. Сохраните этот файл в надежном месте, так как любой, у кого есть этот ключ, может выступать в качестве сервисного аккаунта для доступа к вашим ресурсам Google Cloud Platform. В конце нажмите DONE.

Вы можете открыть сохраненный файл обычным блокнотом (формат .json), чтобы посмотреть, из чего он состоит:

Этот файл вам в дальнейшем понадобится для проекта в Colab.

Чтобы удостовериться в том, что Google сам автоматически создал нам новый проект и учетную запись службы (сервисный аккаунт) в GCP для работы с Data API, перейдите по ссылке console.cloud.google.com. Если в Google Cloud Platform у вас уже созданы и другие проекты, нажмите в верхней части панели на название:

В открывшемся окне сверху выберите вкладку ALL. Вы должны увидеть новый созданный проект с вашим названием:

Нажмите на него, чтобы открыть. Затем перейдите в APIs & Services:

Удостоверьтесь, что в разделе Enabled APIs & services включен Google Analytics Data API:

Нажмите на название. Если Status – Enabled, то Google Analytics Data API включен:

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

Данные по сервисному аккаунту уже присутствуют в выгруженном JSON файле с приватным ключом в строке client_email:

3. Добавление сервисного аккаунта в Google Analytics 4

Скопируйте адрес электронной почты сервисного аккаунта (или из сохраненного файла из поля client_email, или из интерфейса GCP) и откройте свой ресурс Google Analytics 4, с которым планируете работать. Перейдите в раздел Администратор – Ресурс - Управление доступом к ресурсу:

Добавьте нового пользователя:

Для работы с Google Analytics Data API v1 необходимы только разрешения на чтение и анализ (он же Читатель). В поле адреса электронный почты добавьте скопированный на предыдущем шаге e-mail сервисного аккаунта:

В правом верхнем углу нажмите кнопку Добавить. На этом добавление сервисного аккаунта в Google Analytics 4 завершено.

4. Загрузка приватного ключа на Google Диск

Когда вы начнете писать свой первый запрос к Data API, вам понадобятся данные от сервисного аккаунта Google. А для этого необходимо загрузить ваш приватный JSON ключ на Google Диск. Это нужно сделать для того, чтобы после перезапуска среды выполнения (завершения сеанса и закрытия вкладки браузера/проекта) Google не удалял ваш файл с приватным ключом из Colab, и вам не приходилось загружать его каждый раз повторно. Для этого мы подключаемся к Диску и загружаем в него этот файл, а потом в проекте прописываем путь к этому файлу.

Сделать это очень просто. Перейдите в Google Drive по ссылке и загрузите в него ваш приватный ключ:

Перед загрузкой обязательно проверьте, чтобы в имени файла не было никаких пробелов. Если они присутствуют, замените их на нижнее подчеркивание _ или тире -

Написание первого запроса

Все готово к написанию своего первого запроса к Data API (GA4) на Python с использованием клиентской библиотеки, браузера и Colab.

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

Нажмите иконку запуска (значок play), чтобы код в ячейке сработал. В Colab это будет выглядеть так:

Напротив строки с кодом должна появится зеленая галочка, свидетельствующая об успешном выполнении кода:

В конце ячейки вы можете увидеть строчки примерно такого содержания:

Произошла успешная установка пакета, но для использования новых версий вы должны перезапустить среду выполнения с помощью кнопки RESTART RUNTIME. Это делать необязательно, поскольку Google в Colab поддерживает актуальное состояние библиотек и их взаимную работу.

Чтобы продолжить писать программу, сверху вашего блокнота нажмите на + Код:

Под первой ячейкой у вас будет создана новая, пустая:

Теперь импортируйте клиентскую библиотеку Google Cloud с помощью нижеприведенной строчки кода, а затем запустите код в ячейке:

В Colab это будет выглядеть так:

Добавьте новую ячейку с кодом и вставьте в него следующий код:

Он подключает пакет для работы Colab с Google Диском. В Colab это будет выглядеть так:

Вновь добавьте новую ячейку с кодом и вставьте в него следующий код:

Данная строка позволяет импортировать ваши файлы из Google Drive в проект Colab, чтобы потом к ним можно было обращаться в программе. А поскольку на предыдущем шаге вы загрузили свой приватный JSON ключ на Диск, который нам понадобится в составлении запроса к Data API (GA4), запустите ячейку. Вам откроется новое окно, в котором Google попросит вам подключиться к Диску. Сделайте это:

Выбрав свою учетную запись Gmail, предоставьте приложению Google Drive все необходимые разрешения:

В завершение нажмите кнопку Разрешить. После этого код успешно будет выполнен, все всплывающие окна закроются, а в вашем проекте в Colab, если вы нажмете на иконку папки в левом углу страницы, отобразиться папка drive, в которой будут размещены все файлы с вашего Диска, в том числе и загруженный ранее приватный ключ:

Найдите в списке ваш приватный ключ и нажмите на него правой кнопкой мыши. Выберите пункт Скопировать путь:

Как и прежде, создайте новую ячейку с кодом с помощью + Код. Добавьте в нее две строчки кода:

, где вместо путь_к_приватному_файлу.json вы укажете тот путь, который скопировали с предыдущего шага. Затем запустите ячейку с кодом.

В Colab это будет выглядеть так:

Переменная, чье значение присваивается Python извне, называют переменной окружения. Как правило, ее устанавливают в командной строке перед тем, как обратиться к исполняемому файлу Python. После этого ОС позволяет программе Python получать доступ к такой переменной.

Переменные окружения в Python необходимы для гибкости программы. Благодаря им, пользователь получает возможность менять нужные параметры перед выполнением программы. Программа же, в свою очередь, может просматривать изменяемые параметры, динамически подстраивая свое поведение. Т.е. нет необходимости модифицировать код. Такое применение переменных окружения будет называться настройкой программы.

Алгоритм, по которому проходит установка переменных окружения, напрямую зависит от платформы. Поэтому следует использовать встроенный модуль OS компании Python для считывания переменных. Функции этого модуля позволяют взаимодействовать с операционной системой вне зависимости от ее платформы.

Для доступа к таким переменным в Python используется объект os.environ - это словарь, в котором хранятся все переменные окружения программы, а GOOGLE_APPLICATION_CREDENTIALS - это переменная среды, которую нужно задать, чтобы указать расположение вашего приватного ключа JSON. Перед использованием словаря, конечно же, требуется импортировать сам пакет os с помощью команды import os.

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

Вот вы и подошли к кульминации этого руководства - написанию самого запроса к API Google Analytics 4 (Data API). А поскольку мы с вами использовали клиентскую библиотеку на Python, размещенную в официальной документации, то и свой первый запрос составим, ориентируясь на пример из справки Google.

На странице быстрого запуска в самом низу представлен пример кода, позволяющий выгрузить статистику из вашего счетчика Google Analytics 4 за определенный диапазон дат. В качестве параметра задан Город (City), а показателя - Активные пользователи (Active Users). Переключившись на вкладку Python, вы можете увидеть весь запрос целиком:

Код, представленный в справке, можно открыть в Cloud Shell или посмотреть на GitHub:

Если вы в будущем захотите просто скопировать кусок кода и вставить его в свой проект Colab, я рекомендую это делать из гитхаба, поскольку очень важно соблюдать отступы и не использовать в коде лишние пробелы, табуляции и т.д. Скопировав в текущем виде код из официальной документации, он может не сработать.

Поэтому нажмите сверху на кнопку View on GitHub. Вам должна открыться страница проекта:

Прокрутите страницу вниз, пока не дойдете до строки # [START analyticsdata_quickstart]. Именно с этого момента (со следующей строки) и до конца вы должны скопировать приведенный код:

Вставьте этот код в новую ячейку своего проекта Colab, но не запускайте его. Поскольку вы скопировали пример кода, то в нем нужно изменить Идентификатор ресурса (GA4-PROPERTY-ID), а также задать нужные диапазоны дат.

Чтобы найти свой идентификатор ресурса, в интерфейсе GA4 перейдите в раздел Администратор – Настройки ресурса. В правом верхнем углу скопируйте значение идентификатора ресурса:

Вставьте его в скопированном коде в поле property_id:

В самом запросе поменяйте значения start_date (начальная дата) и end_date (конечная дата), за которые хотите выгрузить статистику по городам и активным пользователям. Например, с 1 января по 14 января 2023 года:

Примечание: о том, из чего состоит скопированный из документации код и как самостоятельно формировать такие запросы к Data API методом runReport и другими методами, будет подробнее разобрано в отдельной статье.

После этого вы можете запустить ячейку с кодом (иконка play). Если вы правильно скопировали код, ввели верный идентификатор ресурса, указали диапазон дат, за который у вас есть статистика по городам и активным пользователям, то внизу ячейки вы увидите статистику статистику по активным пользователям с привязкой к городам за выбранный диапазон дат.

Поздравляю! Вы только что создали свой первый запрос к Google Analytics Data API (GA4) и написали первую программу на языке Python без каких-либо навыков программирования, используя только браузер, клиентскую библиотеку Google Analytics и сервис Colab. Было сложно? Возможно, но не так, как вам кажется. Написание запросов к API не сложнее составления формул в Excel. Главное - создать шаблоны таких запросов под различные задачи, а затем запускать их вручную или по расписанию тогда, когда вам требуется. И такие шаблоны будут отличаться лишь выполняемыми методами, наборами параметров, показателей, диапазонами дат и фильтрами.

Ссылка на мой проект Colab, который получился для этого руководства. Используйте его как подсказку или ориентир при создании своего первого запроса.

Сравнение интерфейсных данных и Data API

В завершение этого руководства давайте сравним данные, которые присутствуют в стандартных отчетах Google Analytics 4 и в Исследованиях с теми, которые мы выгрузили благодаря созданному запросу.

Для этого просто откройте отчет Демография - Демографические данные, выберите нужный диапазон дат и измените основной параметр с Страна на Город. Активные пользователи в этом отчете - это просто Пользователи:

Как видите, данные сходятся! Аналогичным образом вы можете поступить, создав Исследование в свободной форме, и добавив в него параметр Город и показатель Активные пользователи:

И здесь статистика точно такая же!

Google Analytics 4 допускает расхождение данных между отчетами и Исследованиями. О том, почему это может происходить, читайте в официальной справке Google.

Что дальше?

Несмотря на то, что вы создали свой первый и самый простой запрос методом runReport к Data API на Python в Colab, вы можете использовать данный проект для выгрузки статистики, но уже с другим набором параметров и показателей, постепенно совершенствуя и дополняя его. О том, как это сделать, будет разобрано в других материалах моего блога.

Главное - сохраните свой проект Colab для последующей работы в нем.