Аутентификация и авторизация

Как и другие API Google, Google Ads API использует протокол OAuth 2.0 для аутентификации и авторизации. OAuth 2.0 позволяет API-клиенту Google Ads API получать доступ к аккаунту Google Рекламы без необходимости обрабатывать или хранить данные для входа.

В этом руководстве рассказывается, как настроить клиентскую библиотеку Java для аутентификации Google Ads API с помощью трех наиболее распространенных процессов OAuth 2.0, а также объясняется, какие учетные данные требуются.

Подробную информацию о модели доступа Google Ads API можно найти в руководстве по модели доступа Google Рекламы.

Учетные данные

Для доступа к Google Ads API требуются учетные данные OAuth 2.0, а в некоторых случаях – идентификатор клиента.

Учетные данные OAuth 2.0

Чтобы авторизоваться в качестве пользователя аккаунта Google с доступом к аккаунтам Google Рекламы, необходимо предоставить набор учетных данных OAuth 2.0. Тип необходимых учетных данных зависит от используемого процесса OAuth 2.0.

Библиотека поддерживает три процесса:

  • Процесс для сервисного аккаунта
  • Процесс аутентификации одного пользователя
  • Процесс аутентификации нескольких пользователей

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

Идентификатор клиента для входа

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

В клиентской библиотеке идентификатор клиента, выполнившего вход, указывается с помощью ключа api.googleads.loginCustomerId в файле ads.properties.

Конфигурация

Вы можете настроить клиентскую библиотеку с помощью файла ads.properties, переменных среды или программно. В этом руководстве мы рассмотрим использование файла ads.properties. Подробная информация обо всех вариантах приведена в руководстве по настройке.

Если вы используете файл ads.properties, поместите его в домашний каталог: ~/ads.properties.

Рабочие процессы OAuth

При работе с Google Ads API обычно используются три рабочих процесса.

Процесс для сервисного аккаунта

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

Получив JSON-файл закрытого ключа, добавьте в файл ads.properties следующее:

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

Подробную информацию вы найдете в руководстве по работе с сервисными аккаунтами.

Процесс аутентификации одного пользователя

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

  1. Предоставьте одному пользователю доступ ко всем аккаунтам, которыми нужно управлять с помощью Google Ads API. Обычно пользователю предоставляют доступ к управляющему аккаунту Google Ads API и связывают с ним все целевые аккаунты Google Рекламы.
  2. Пользователь запускает инструмент командной строки, например gcloud CLI или пример кода GenerateUserCredentials, чтобы разрешить вашему приложению управлять всеми его аккаунтами Google Рекламы от его имени.

Получив эти учетные данные, добавьте в файл ads.properties следующий код:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

Подробную информацию можно найти в руководстве по аутентификации одного пользователя.

Процесс аутентификации нескольких пользователей

Это рекомендуемый рабочий процесс, если ваше приложение позволяет пользователям входить в систему и разрешать вашему приложению управлять своими аккаунтами Google Рекламы от их имени. Пример кода GenerateUserCredentials – это инструмент командной строки, который показывает, как получить аутентификацию пользователя во время выполнения, чтобы управлять его аккаунтами Google Рекламы от его имени. Вы можете использовать этот пример кода в качестве справки при создании компьютерных или веб-приложений, требующих аутентификации пользователей.

Если у вас многопользовательское приложение, храните идентификатор клиента OAuth 2.0 и секретный код клиента в файле ads.properties (или другом хранилище конфигураций). При этом токен обновления каждого конечного пользователя должен храниться в базе данных приложения и передаваться программно во время выполнения при создании UserCredentials и GoogleAdsClient.

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

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

Управление несколькими аккаунтами

Пользователи часто управляют несколькими аккаунтами Google Рекламы, используя прямой доступ к ним или управляющий аккаунт Google Рекламы. В клиентской библиотеке Java есть примеры кода, которые показывают, как обрабатывать такие случаи:

  1. Пример кода на GetAccountHierarchy показывает, как получить список всех аккаунтов, связанных с управляющим аккаунтом Google Рекламы.
  2. В примере кода ListAccessibleCustomers показано, как получить список всех аккаунтов, к которым у пользователя есть прямой доступ. Эти аккаунты можно использовать в качестве допустимых значений для настройки loginCustomerId.

Application Default Credentials

Клиентская библиотека Java также поддерживает аутентификацию с помощью Application Default Credentials.

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

Для Google Ads API убедитесь, что у Application Default Credentials есть доступ к области действия OAuth 2.0 https://www.googleapis.com/auth/adwords.

Чтобы использовать Application Default Credentials, задайте для параметра api.googleads.useApplicationDefaultCredentials значение true в файле ads.properties (или вызовите .enableApplicationDefaultCredentials() для GoogleAdsClient.newBuilder()). При использовании Application Default Credentials не нужно задавать идентификатор клиента, секретный код клиента и токен обновления.