Ник Михайловски, команда Google Analytics API – август 2012 г.
В этом руководстве описывается, как получить доступ к API управления и основной отчетности в Google Sheets с помощью Apps Script.
Введение
Вы можете использовать API Google Analytics и скрипт Google Apps для доступа к данным Google Analytics из Google Таблиц . Это мощный инструмент, поскольку позволяет вам использовать все замечательные функции Google Таблиц с вашими аналитическими данными, такие как инструменты простого обмена, совместной работы, построения диаграмм и визуализации.
В этом руководстве вы познакомитесь с кодом, необходимым для доступа к вашим данным Google Analytics в Google Sheets с помощью скрипта Google Apps.
Обзор
В этом руководстве показано, как зарегистрироваться и настроить среду Apps Script для использования API Google Analytics. После настройки в руководстве рассказывается, как получить идентификатор представления (профиля) авторизованного пользователя с помощью Management API . Затем, как использовать идентификатор представления (профиля) для запроса к Core Reporting API , чтобы получить 250 самых популярных ключевых слов мобильного поиска от Google. Наконец, результаты будут вставлены в электронную таблицу Google. Если у вас есть данные, в руководстве также обсуждается, как автоматизировать получение данных.
Когда вы создаете приложение с использованием API Google Analytics и скрипта приложений, вы обычно выполняете следующие шаги:
- Включите API Google Analytics в Google Таблицах.
- Работа с API Google Analytics.
Давайте подробно разберем каждый шаг.
Включите API Google Analytics в скрипте приложений
Чтобы включить доступ к вашим данным Google Analytics из Google Таблиц, выполните следующие действия:
- Создайте файл Google Таблиц. Дайте этому крутое имя.
- Создайте новый скрипт приложений.
- В меню выберите «Расширения» > «Скрипт приложений» .
- Если появится всплывающее меню, просто нажмите «Пустой проект» .
- Дайте проекту имя. Убедитесь, что у него крутое имя.
Если у вас есть новый скрипт, вам необходимо включить службу Google Analytics .
- В редакторе скриптов выберите Ресурсы > Расширенные службы Google...
- В появившемся диалоговом окне нажмите переключатель включения/выключения рядом с API Google Analytics.
- В нижней части диалогового окна нажмите ссылку на консоль разработчика Google .
- В новой консоли снова нажмите переключатель включения/выключения рядом с API Google Analytics. (После включения он переместится в верхнюю часть страницы.)
- Вернитесь в редактор сценариев и нажмите «ОК» в диалоговом окне.
Должно появиться небольшое желтое диалоговое окно с сообщением о том, что вы успешно добавили новую службу Google API в свой скрипт. Теперь вы готовы начать писать свой первый сценарий.
Работайте с API Google Analytics.
Этот скрипт в этом руководстве запросит у Google Analytics API 250 самых популярных ключевых слов мобильного поиска Google, а затем выведет результаты в Google Таблицы. Для этого скрипт выполнит следующие шаги:
- Получить первое представление (профиль) авторизованного пользователя.
- Запросите данные у Core Reporting API.
- Вставьте данные в электронную таблицу.
Добавьте следующую функцию в пустой проект.
function runDemo() { try { var firstProfile = getFirstProfile(); var results = getReportDataForProfile(firstProfile); outputToSpreadsheet(results); } catch(error) { Browser.msgBox(error.message); } }
В приведенном выше коде блок try...catch
используется для обработки любых ошибок API. Если возникнут какие-либо ошибки, выполнение программы будет остановлено, и ошибка будет отображена в окне сообщения. В блоке try
функция используется для выполнения каждого шага, который проходит скрипт. Давайте теперь добавим код для каждой из этих функций.
Получить первый просмотр авторизованного пользователя (профиль)
В Google Analytics каждый отчет принадлежит представлению (профилю) и идентифицируется идентификатором представления (профиля). Поэтому, когда вы указываете запрос к данным отчета, вы также должны указать идентификатор представления (профиля) представления (профиля), из которого вы хотите получить данные.
API управления Google Analytics предоставляет доступ ко всем учетным записям, веб-ресурсам и объектам представления (профиля), принадлежащим пользователю. Каждая из этих сущностей принадлежит к иерархии, и вы можете программно перемещаться по этой иерархии, чтобы получить идентификатор представления (профиля) авторизованного пользователя.
Вторая функция, которую мы напишем, будет проходить вниз по иерархии Management API и возвращать первое представление (профиль) пользователя. Скопируйте и вставьте следующий код в свой проект Apps Script:
function getFirstProfile() { var accounts = Analytics.Management.Accounts.list(); if (accounts.getItems()) { var firstAccountId = accounts.getItems()[0].getId(); var webProperties = Analytics.Management.Webproperties.list(firstAccountId); if (webProperties.getItems()) { var firstWebPropertyId = webProperties.getItems()[0].getId(); var profiles = Analytics.Management.Profiles.list(firstAccountId, firstWebPropertyId); if (profiles.getItems()) { var firstProfile = profiles.getItems()[0]; return firstProfile; } else { throw new Error('No views (profiles) found.'); } } else { throw new Error('No webproperties found.'); } } else { throw new Error('No accounts found.'); } }
В этой функции сначала запрашивается коллекция учетных записей с использованием метода Analytics.Management.Accounts.list
. Если у авторизованного пользователя есть учетные записи Google Analytics, извлекается идентификатор первой учетной записи. Затем коллекция веб-ресурсов запрашивается путем вызова метода Analytics.Management.Webproperties.list
и передачи ему идентификатора учетной записи, полученного на предыдущем шаге. Если веб-ресурсы существуют, коллекция представлений (профилей) окончательно запрашивается с помощью метода Analytics.Management.Profiles.list
. Идентификатор учетной записи и идентификаторы веб-ресурса передаются в качестве параметров этому методу. Если представления (профили) существуют, возвращается первое представление (профиль).
Если в какой-либо момент возникает ошибка API или если ответ API не содержит результатов, выдается ошибка с сообщением о том, что результаты не найдены. Блок catch
в приведенной выше функции runDemo
уловит эту ошибку и распечатает сообщение пользователю.
После завершения работы скрипта он теперь может запрашивать данные отчета.
Запросите данные у Core Reporting API.
Получив идентификатор представления (профиля), вы используете Core Reporting API для запроса данных отчетов Google Analytics. В этом разделе вы узнаете, как отправлять запросы к этому API с помощью Apps Script.
Добавьте следующий код в проект Apps Script:
function getReportDataForProfile(firstProfile) { var profileId = firstProfile.getId(); var tableId = 'ga:' + profileId; var startDate = getLastNdays(14); // 2 weeks (a fortnight) ago. var endDate = getLastNdays(0); // Today. var optArgs = { 'dimensions': 'ga:keyword', // Comma separated list of dimensions. 'sort': '-ga:sessions,ga:keyword', // Sort by sessions descending, then keyword. 'segment': 'dynamic::ga:isMobile==Yes', // Process only mobile traffic. 'filters': 'ga:source==google', // Display only google traffic. 'start-index': '1', 'max-results': '250' // Display the first 250 results. }; // Make a request to the API. var results = Analytics.Data.Ga.get( tableId, // Table id (format ga:xxxxxx). startDate, // Start-date (format yyyy-MM-dd). endDate, // End-date (format yyyy-MM-dd). 'ga:sessions,ga:pageviews', // Comma seperated list of metrics. optArgs); if (results.getRows()) { return results; } else { throw new Error('No views (profiles) found'); } } function getLastNdays(nDaysAgo) { var today = new Date(); var before = new Date(); before.setDate(today.getDate() - nDaysAgo); return Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd'); }
Первая часть кода создает запрос Core Reporting API с использованием метода Analytics.Data.Ga.get
. Метод принимает набор параметров, определяющих тип получаемого отчета. Каждый запрос Core Reporting API состоит из набора обязательных и необязательных параметров. Обязательные параметры передаются методу как параметры, а необязательные параметры передаются как объект.
Параметр table ID
является обязательным и формируется путем присоединения префикса ga:
к идентификатору представления (профиля). Код создает идентификатор таблицы, используя идентификатор представления (профиля), полученный на предыдущем шаге. Также необходимы даты начала и окончания и укажите диапазон дат для получения данных. Оба значения рассчитываются на основе сегодняшней даты с использованием функции getLastNdays
. Наконец, все необязательные параметры передаются функции с помощью объекта optArgs
.
При запуске метода Analytics.Data.Ga.get
выполняется запрос к Core Reporting API. Если возникает ошибка, она перехватывается в блоке try...catch
, определенном во внешнем методе runDemo
. Если запрос прошел успешно, возвращаются результаты.
Вставьте данные в электронную таблицу
Последним шагом в нашем скрипте является вывод результатов из Core Reporting API в Google Таблицы. Эту работу выполняет метод outputToSpreadsheet
. Добавьте в свой проект следующий код:
function outputToSpreadsheet(results) { var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet(); // Print the headers. var headerNames = []; for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) { headerNames.push(header.getName()); } sheet.getRange(1, 1, 1, headerNames.length) .setValues([headerNames]); // Print the rows of data. sheet.getRange(2, 1, results.getRows().length, headerNames.length) .setValues(results.getRows()); }
Эта функция сначала вставляет новый лист в активную электронную таблицу. Затем он вставляет в лист все данные заголовка и отчета. Дополнительные советы о том, как вставлять данные в Google Таблицы, можно найти в статье «Запись данных из объектов JavaScript в электронную таблицу» в руководстве «Хранение данных в электронных таблицах» .
Запустить сценарий
Добавив весь код в проект, вы можете его запустить.
- На панели инструментов редактора скриптов в раскрывающемся списке выбора функции выберите
runDemo
. - Далее нажмите кнопку
play
.
При первом запуске появится всплывающее окно, в котором вам потребуется авторизовать этот скрипт для доступа к данным вашей учетной записи Google Analytics.
Нажмите авторизовать.
После нажатия откроется новая страница, размещенная на google.com, и вам будет предложено предоставить этому скрипту доступ к вашим данным. Как только вы нажмете «Разрешить», вы будете перенаправлены на страницу подтверждения. На этом этапе ваш скрипт получит доступ к вашим данным Google Analytics и сможет продолжить выполнение.
После запуска скрипта перейдите в окно с Google Таблицами. Вы должны увидеть все данные ключевых слов, возвращенные API, или окно сообщения с сообщением об ошибке.
Автоматизируйте сценарий
На этом этапе у вас должен быть скрипт, который запрашивает API Google Analytics. Возможно, теперь вы захотите автоматизировать этот сценарий, чтобы получать новые данные каждую ночь. Apps Script упрощает автоматизацию с помощью функции triggers
.
Чтобы автоматизировать этот скрипт, выполните следующие шаги:
- На панели инструментов редактора скриптов нажмите
Resources -> All your triggers...
- Нажмите
Add a new trigger
. Появится диалоговое окно триггеров. - Настройте триггер для выполнения метода
runDemo
каждую ночь.- В раскрывающемся списке
Run
должно быть установлено значение:runDemo
- В раскрывающемся списке
Events
должны быть установлены значения:Time-driven
,Day timer
» иMidnight to 1am
.
- В раскрывающемся списке
После настройки этот сценарий будет запускаться каждую ночь, предоставляя вам свежие данные утром.
Если какие-либо ошибки возникнут ночью, вы захотите получить уведомление. Apps Script также позволяет отправлять оповещения по электронной почте в случае возникновения каких-либо сбоев. Чтобы настроить это, в диалоговом окне триггеров щелкните ссылку notifications
. Появится новое диалоговое окно, в котором вы сможете указать, на какой адрес электронной почты вы хотите отправлять ошибки.
Заключение
вы успешно зарегистрировались и разрешили доступ к своему скрипту. Вы несколько раз запросили Management API, чтобы получить идентификатор представления (профиля). Затем вы использовали идентификатор представления (профиля) для запроса к Core Reporting API для получения данных и вывода их в Google Sheets.
Использование методов, описанных в руководстве, позволит вам выполнить более сложный анализ, получить более глубокое понимание, создать собственные информационные панели и сократить время на создание отчетов вручную.
Еще несколько интересных руководств, которые могут оказаться полезными и помогут вам максимально эффективно использовать API Google Analytics и скрипт Google Apps:
- Чтение данных из электронных таблиц . Таким образом, вы можете указывать запросы API в электронной таблице, а не в JavaScript.
- Вставка диаграмм из электронных таблиц на сайт Google . Таким образом, вы можете создавать информационные панели на сайтах Google с вашими данными аналитики.
- Пользовательские меню . Чтобы другие пользователи в вашей компании могли легко использовать написанные вами сценарии.