Авторизация в 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 для Google Tag Manager API:

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

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

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

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

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

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

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

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

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

Веб-сервер

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

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

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

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

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

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

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

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

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

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

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

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

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

OAuth 2.0 Playground

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

Ошибка invalid_grant

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

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