Руководство для разработчиков

В этом документе описывается, как использовать API отчетов в реальном времени для получения данных Google Analytics.

Введение

API отчетов в реальном времени позволяет вам сообщать о действиях, происходящих на вашем объекте прямо сейчас. Чтобы получить доступ к данным в реальном времени, вы создаете запрос, в котором указывается представление (профиль) и хотя бы одна метрика. Вы также можете указать дополнительные параметры запроса, такие как параметры и фильтры, для уточнения запроса. Этот запрос отправляется в API отчетов в реальном времени, который возвращает данные в виде таблицы.

Если вы новичок в API, прочтите Обзор API отчетов в реальном времени , чтобы получить представление об API отчетов в реальном времени и данных, которые он предоставляет.

Предварительное условие

Прежде чем использовать API отчетов в реальном времени для получения данных Google Analytics:

  • Прочтите страницу клиентских библиотек , чтобы получить полный список клиентских библиотек для конкретного языка программирования, которые работают с API.
  • Прочтите Справочное руководство , чтобы узнать, как использовать только API (без использования клиентской библиотеки) для получения данных Google Analytics.

Каждая клиентская библиотека предоставляет один объект службы аналитики для доступа ко всем данным API отчетов в реальном времени. Чтобы создать объект службы:

  1. Зарегистрируйте свое приложение в консоли Google API .
  2. Разрешите доступ к данным Google Analytics.
  3. Создайте объект службы Analytics.

Если вы еще не выполнили эти шаги, остановитесь и прочитайте руководство Hello Google Analytics API , которое проведет вас через начальные этапы создания приложения Google Analytics API. После этого вы знаете, как использовать API для получения данных Google Analytics.

Использование API отчетов в реальном времени

Чтобы использовать API отчетов в реальном времени, приложение:

  1. Запрашивает API отчетов в реальном времени.
  2. Обрабатывает ответ API.

Запрос к API отчетов в реальном времени

Объект службы аналитики предоставляет метод для создания запроса API отчетов в реальном времени. Подробную информацию о параметрах запроса и данных, доступных API, читайте:

После определения запроса вызовите его метод execute , чтобы отправить запрос на серверы Google Analytics.

Обработка ответа API

Если запрос к API отчетов в реальном времени успешен, API возвращает запрошенные данные как часть ресурса данных в реальном времени. Подробную информацию о структуре и формате ответа API см. в справочнике по API отчетов в реальном времени .

Если возникают какие-либо ошибки, API возвращает конкретный код состояния и сообщение с описанием ошибки. Все приложения должны ловить и обрабатывать ошибки. Подробный список ошибок и рекомендации по повторным попыткам см. в разделе «Ответы на ошибки» .

Примеры кода

В разделе «Примеры» на странице «Данные в реальном времени: получить » представлен пример кода на различных языках программирования для запроса API отчетов в реальном времени и обработки ответа API.

Ограничения запроса

Вот ограничения на запросы API реального времени:

  • Если метрика rt:activeUsers включена в запрос со следующими фильтрами измерений, то поддерживаются только оператор AND и тип соответствия равенства ( == ).
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    Поскольку метрика rt:activeUsers извлекает только количество активных пользователей на сайте в данный момент, не используйте rt:minutesAgo с rt:activeUsers . То есть rt:activeUsers подразумевает, что rt:minutesAgo равно 0.

  • Фильтры метрик не поддерживаются.
  • Параметр fields не поддерживается.

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

Как описано в разделе «Ограничения и квоты» , для API отчетов в реальном времени существуют ежедневные квоты, которые используются совместно с другими API Google Analytics. Если вы опрашиваете API отчетов в реальном времени через короткие промежутки времени, вы очень быстро достигнете пределов дневной квоты. В этом случае запросы от других API Google Analytics также перестают работать до тех пор, пока квота не будет обновлена.

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

  • У вас есть несколько информационных панелей в реальном времени, которые ежедневно запрашивают данные для одного представления (профиля) Google Analytics через очень короткие промежутки времени.
  • У вас есть ресурс с большим количеством пользователей, и вы внедрили виджет реального времени. Каждый раз, когда виджет отображается пользователю, вы напрямую запрашиваете Google Analytics, а не используете кеш.

Чтобы свести к минимуму использование квот и эффективно управлять ими:

  • Внедрить кэширование на стороне сервера . Когда несколько пользователей отправляют запрос на одни и те же данные в реальном времени, вам следует вернуть кэшированный ответ вместо прямого запроса к API отчетов в реальном времени для запроса каждого пользователя. Затем периодически обновляйте кэш последними данными в реальном времени с разумным интервалом обновления, чтобы избежать превышения дневных ограничений квоты.
  • Объедините несколько запросов, указав дополнительные измерения, и проанализируйте ответ на стороне сервера или клиента.
  • Увеличьте интервал времени, через который вы запрашиваете данные в реальном времени.

Пример: расчет интервала обновления

Если вы планируете регулярно запрашивать данные в реальном времени, вам следует выбрать разумный интервал обновления в зависимости от ожидаемого использования.

Например, одно представление (профиль) Google Analytics имеет ежедневную квоту в 10 000 запросов в день. Если в течение одного дня вы планируете выполнить 6000 запросов к Core Reporting API для одного представления (профиля), то для этого представления (профиля) у вас останется квота в 4000 запросов.

Предположим, вы решили использовать API отчетов в реальном времени для реализации трех информационных панелей в реальном времени, которые в течение всего дня выполняют запросы к данным в реальном времени из одного и того же представления (профиля). Каждая панель мониторинга может выполнять примерно 1333 запроса в день (4000 запросов / 3 панели мониторинга). В сутках 86400 секунд. Таким образом, интервал обновления для каждой информационной панели должен быть больше 65 секунд (86 400/1 333), чтобы общее количество ежедневных запросов к представлению (профилю) было ниже дневного лимита в 4 000.