Авторизация API Диспетчера тегов

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

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

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

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

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

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

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

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

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

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

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

Вот информация об области действия OAuth 2.0 для 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 предоставляет при регистрации вашего приложения (например, идентификатор клиента и секрет клиента).

Начиная

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

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

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

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

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

Следующие рекомендации описывают распространенные варианты использования для конкретных потоков OAuth 2.0:

Веб сервер

Этот поток хорош для автоматического/автономного/запланированного доступа к учетной записи Google Tag Manager пользователя.

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

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

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

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

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

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

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

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

Полезно для автоматического/автономного/запланированного доступа к вашей собственной учетной записи Диспетчера тегов Google. Например, чтобы создать собственный инструмент для мониторинга вашей собственной учетной записи Диспетчера тегов Google и поделиться ею с другими пользователями.

Исправление проблем

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

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

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

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

Недействительный грант

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

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