Core Reporting API: авторизация

В этой статье описывается авторизация запросов из приложения к Core Reporting API.

Авторизация запросов

Чтобы просматривать свои данные в Google Analytics, нужно войти в аккаунт. Аналогичным образом, когда пользователь впервые запускает ваше приложение, он должен дать разрешение на доступ к данным.

Каждый запрос из вашего приложения к Google Analytics API должен содержать токен авторизации, который одновременно является идентификатором вашего приложения для Google.

Протоколы авторизации

Для авторизации запросов ваше приложение должно использовать протокол OAuth 2.0. Другие протоколы авторизации не поддерживаются. Если в вашем приложении используется вход с аккаунтом Google, некоторые аспекты авторизации реализуются автоматически.

Авторизация запросов с использованием OAuth 2.0

Все запросы к Google Analytics API должны быть разрешены пользователем, прошедшим аутентификацию.

Особенности процесса авторизации с помощью OAuth 2.0 зависят от типа приложения. В общих чертах процедура выглядит так:

  1. Сначала приложение нужно зарегистрировать через Google API Console. Вы получите информацию, которая пригодится позже, например идентификатор и секретный код клиента.
  2. Активируйте Analytics API в Google API Console. Если такого API в консоли нет, пропустите этот шаг.
  3. Если приложению требуются пользовательские данные, оно запрашивает у Google нужную область доступа.
  4. Google показывает пользователю диалоговое окно с предложением авторизовать приложение для запроса этих данных.
  5. Если пользователь соглашается, Google предоставляет приложению токен доступа с коротким сроком действия.
  6. Ваше приложение запрашивает пользовательские данные, указывая токен доступа.
  7. Получив действительный запрос и токен, Google возвращает необходимые данные.

Иногда процесс может включать дополнительные этапы, например использование токенов обновления для получения новых токенов доступа. Подробнее об авторизации различных типов приложений читайте в документации по OAuth 2.0.

Информация об области доступа OAuth 2.0 для Google Analytics API:

Область доступа Значение
https://www.googleapis.com/auth/analytics.readonly Доступ к Google Analytics API только для чтения.

Чтобы запросить доступ с помощью OAuth 2.0, приложению нужна информация об области доступа наряду с данными, которые Google предоставляет при регистрации приложения (например, идентификатор или секретный ключ клиента).

Совет. Клиентские библиотеки API Google автоматически выполняют часть задач, связанных с авторизацией. Они доступны для различных языков программирования. Дополнительную информацию можно получить на странице Библиотеки и примеры кода.

Распространенные процессы аутентификации OAuth 2.0

В этом разделе приводятся советы по применению процессов аутентификации OAuth 2.0.

Веб-сервер

Этот вариант наиболее эффективен, если вы получаете доступ к данным о пользователях в Google Analytics в автоматическом режиме, офлайн или по расписанию.

Пример:

  • Автоматическое обновление пользовательских сводок с загрузкой актуальных данных Google Analytics.

Сторона клиента

Рекомендуется, если пользователь непосредственно взаимодействует с приложением для доступа к данным Google Analytics из браузера. Этот вариант не подразумевает использование функций на стороне сервера, и поэтому не позволяет создавать отчеты в автоматическом режиме, офлайн или по расписанию.

Пример:

Установленные приложения

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

Примеры:

  • Виджет рабочего стола на компьютере.
  • Плагин для системы управления контентом. В отличие от двух первых процессов, приложению можно выделить один проект в API Console. Это позволяет создавать сводные отчеты и упрощает процесс установки для пользователей.

Сервисные аккаунты

Этот вариант следует выбрать, если вы получаете доступ к данным Google Analytics из своего аккаунта в автоматическом режиме, офлайн или по расписанию. Например, вы можете создать интерактивную сводку собственных данных Google Analytics, которая будет доступна другим пользователям.

Чтобы начать работать с Analytics API, нужно сначала воспользоваться инструментом настройки. С его помощью можно создать проект в Google API Console, активировать API и получить учетные данные.

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

  1. Нажмите Создать учетные данные > Ключ сервисного аккаунта.
  2. Выберите формат, в котором вы хотите скачать открытый/закрытый ключ аккаунта приложения: стандартный файл P12 или файл JSON, который может быть загружен клиентской библиотекой Google API.

Система создаст единственную пару ключей (открытый и закрытый), которая затем будет передана на ваш компьютер. Вы должны самостоятельно обеспечивать ее сохранность.

Устранение неполадок

Если авторизация не будет выполнена, появится сообщение об ошибке с кодом. Кодов бывает два:

  • Код статуса 401 означает, что истек срок действия токена доступа access_token или для API задана неверная область действия.

  • Код статуса 403 возвращается, если у пользователя нет доступа к представлению (профилю). Убедитесь, что у пользователя есть соответствующие права.

Площадка для экспериментов с OAuth 2.0

Здесь вы можете пройти весь процесс авторизации через веб-интерфейс и узнать, какие заголовки HTTP нужно включать в запросы. Площадка для экспериментов позволяет работать с приложением даже при отсутствии разрешений. Сравните запросы и заголовки HTTP с теми, которые ваше приложение отправляет в Google Analytics, и убедитесь, что используете верный формат.

Ошибка invalid_grant

При попытке использовать токен обновления иногда возникает ошибка invalid_grant. Она вызвана одной из следующих причин:

  • Время сервера не синхронизировано с протоколом NTP.
  • Превышено ограничение на количество токенов обновления.

Приложения могут запрашивать несколько токенов обновления для доступа к одному аккаунту Google Analytics.

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

Для каждой пары из клиента OAuth 2.0 и аккаунта Google Analytics действует ограничение в 25 токенов обновления. Соответственно, с выпуском 26-го токена становится недействительным первый, с созданием 27-го – второй и так далее.