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

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

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

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

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

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

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

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

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

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

  1. Создавая приложение, вы регистрируете его в Google Developers Console. Вы получите информацию, которая пригодится позже, например идентификатор и секретный ключ клиента.
  2. Вы включаете Google Analytics API в Google Developers 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 из браузера. Работает без использования функций на стороне сервера, в результате чего не подходит для создания отчетов в автоматическом режиме, офлайн или по расписанию.

Пример:

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

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

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

Аккаунты приложений

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

Настройка аккаунтов приложений для работы с Google Analytics выполняется в несколько этапов.

Для работы с Analytics API сначала необходимо создать или выбрать проект в Google Developers Console и включить API (после выполнения инструкций API будет активирован автоматически).

Также вы можете активировать Analytics API самостоятельно с помощью Developers Console:

  1. Откройте страницу Credentials (Учетные данные).

В обоих случаях откроется страница Credentials (Учетные данные), на которой вы сможете их ввести.

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

  1. Нажмите Add credentials > Service account (Добавить учетные данные > Аккаунт приложения).
  2. Выберите формат для скачивания открытого/секретного ключа аккаунта приложения: стандартный файл P12 или файл JSON, который может быть загружен клиентской библиотекой Google API.

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

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

Если вы сталкиваетесь с ошибками аутентификации и получаете коды статуса 401 или 403, попробуйте описанные здесь решения.

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

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

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

Площадка для экспериментов с OAuth 1.0. Аналогичный инструмент для предыдущей версии протокола OAuth.

Ошибка invalid_grant

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

  1. Время сервера не синхронизировано с протоколом NTP.
  2. Превышено ограничение на количество токенов обновления.
    Приложения могут запрашивать несколько токенов обновления для доступа к одному аккаунту Google Analytics. Например, это нужно для установки приложения на несколько компьютеров и последующего доступа к нему под одним аккаунтом Google Analytics. В этом случае для каждой установки требуется свой токен обновления. При превышении ограничения на количество токенов более старые токены становятся недействительными. При попытке использовать такие токены возвращается ошибка invalid_grant. Для каждой пары из клиента OAuth 2.0 и аккаунта Google Analytics устанавливается ограничение в 25 токенов обновления, которое может быть изменено. Соответственно, с выпуском 26-го токена становится недействительным первый, затем второй и так далее.