Авторизация в Tag Manager API

В этой статье рассказывается, как открыть приложению доступ на выполнение запросов к Tag Manager API.

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

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

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

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

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

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

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

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

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

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

Ниже приведена информация об областях доступа OAuth 2.0 для Tag Manager API.

Область доступа Значение
https://www.googleapis.com/auth/tagmanager.readonly Просмотр контейнеров Менеджера тегов.
https://www.googleapis.com/auth/tagmanager.edit.containers Управление контейнерами Менеджера тегов.
https://www.googleapis.com/auth/tagmanager.delete.containers Удаление контейнеров Менеджера тегов.
https://www.googleapis.com/auth/tagmanager.edit.containerversions Управление версиями контейнеров Менеджера тегов.
https://www.googleapis.com/auth/tagmanager.publish Публикация контейнеров Менеджера тегов.
https://www.googleapis.com/auth/tagmanager.manage.users Управление пользовательскими разрешениями для доступа к данным Менеджера тегов.
https://www.googleapis.com/auth/tagmanager.manage.accounts Управление аккаунтами Менеджера тегов.

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

Начало работы

Перед началом работы с Google Tag Manager API воспользуйтесь этим инструментом настройки, чтобы создать проект в Google API Console, включить API и зарегистрировать учетные данные.

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

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

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

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

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

Аутентификация веб-сервера

Этот способ хорошо подходит для доступа к аккаунту Менеджера тегов в автоматическом режиме, офлайн или по расписанию.

Пример:
  • Автоматическое обновление данных Менеджера тегов с сервера.

Аутентификация на стороне клиента

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

Пример:
  • Персонализированные средства настройки в браузере.

Аутентификация установленных приложений

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

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

Аутентификация сервисных аккаунтов

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

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

Если срок действия токена access_token истек или вы указали неверную область доступа для вызова API, в ответе будет возвращен код состояния 401.

Если у авторизованного пользователя нет доступа к аккаунту или контейнеру Менеджера тегов, в ответе будет возвращен код состояния 403. В этом случае убедитесь, что выбран верный пользователь и что у него есть разрешения на доступ к этому аккаунту или контейнеру Менеджера тегов.

OAuth 2.0 Playground

Инструмент OAuth 2.0 Playground позволяет проходить всю процедуру авторизации через веб-интерфейс. Также он показывает, какие заголовки HTTP нужно включать в запросы авторизации. С его помощью вы сможете начать работу с приложением, даже если вам не удалось авторизоваться: сравните заголовки HTTP с запросами, которые отправляет ваше приложение, и исправьте возможные ошибки в формате.

Ошибка invalid_grant

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

  1. Время сервера не синхронизировано с протоколом NTP.
  2. Вы превысили лимит для токена обновления.
    Приложения могут запрашивать несколько токенов обновления для доступа к одному аккаунту Менеджера тегов. Например, это происходит, когда пользователь хочет установить приложение на несколько компьютеров. В этом случае для каждой установки требуется свой токен обновления. При превышении ограничения на количество токенов более старые токены становятся недействительными. При попытке использовать такие токены возвращается ошибка invalid_grant. Для каждой уникальной комбинации идентификатора клиента и аккаунта допускается до 25 токенов обновления (размер этого лимита может быть изменен). Соответственно, с выпуском 26-го токена становится недействительным первый, с выпуском 27-го – второй и т. д.