API управления – авторизация

В этом руководстве описывается, как приложение авторизует запросы к Management API.

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

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

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

О протоколах авторизации

Ваше приложение должно использовать OAuth 2.0 для авторизации запросов. Никакие другие протоколы авторизации не поддерживаются. Если ваше приложение использует «Войти через Google» , некоторые аспекты авторизации выполняются за вас.

Авторизация запросов с помощью OAuth 2.0

Все запросы к Analytics API должны быть авторизованы авторизованным пользователем.

Детали процесса авторизации или «потока» для OAuth 2.0 несколько различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применим ко всем типам приложений:

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

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

Вот информация об области действия OAuth 2.0 для Analytics API:

Объем Значение
https://www.googleapis.com/auth/analytics.readonly Доступ только для чтения к Analytics API.
https://www.googleapis.com/auth/analytics.edit Редактировать объекты управления Google Analytics.
https://www.googleapis.com/auth/analytics.manage.users Просмотр и управление разрешениями пользователей для учетных записей Google Analytics.
https://www.googleapis.com/auth/analytics.manage.users.readonly Просмотр разрешений пользователей Google Analytics.

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

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

Общие потоки OAuth 2.0

Ниже перечислены распространенные варианты использования конкретных потоков OAuth 2.0:

Веб сервер

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

Пример:

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

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

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

Пример:

  • Инструмент создания отчетов на основе браузера, например Analytics Query Explorer .

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

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

Примеры:

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

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

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

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

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

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

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

Поиск неисправностей

Ваша авторизация не удалась в следующих ситуациях:

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

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

Игровая площадка OAuth 2.0

Этот инструмент позволяет пройти весь процесс авторизации через веб-интерфейс. Инструмент также отображает все заголовки HTTP-запросов, необходимые для выполнения авторизованного запроса. Если вы не можете получить авторизацию для работы в собственном приложении, попробуйте заставить его работать через площадку OAuth 2.0. Затем вы можете сравнить HTTP-заголовки и запросы с игровой площадки с тем, что ваше приложение отправляет в Google Analytics. Эта проверка — простой способ убедиться, что вы правильно форматируете запросы.

Неверный грант

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

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

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

Ограничение для каждой уникальной пары клиента OAuth 2.0 и учетной записи Google Analytics составляет 25 токенов обновления . Если приложение продолжает запрашивать токены обновления для той же пары «Клиент/Учетная запись», то после выдачи 26-го токена первый выданный ранее токен обновления станет недействительным. 27-й запрошенный токен обновления аннулирует второй ранее выданный токен и так далее.