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

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

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

Для более подробного ознакомления с моделью доступа к API Google Ads, прочтите руководство по модели доступа к Google Ads .

Реквизиты для входа

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

токен разработчика

Токен разработчика привязан к учетной записи администратора и находится в веб-интерфейсе Google Ads .

Хотя токен разработчика привязан к учетной записи менеджера, он не предоставляет доступ к этой учетной записи. Вместо этого токен разработчика предоставляет доступ к API в целом, а доступ на уровне учетной записи настраивается через OAuth 2.0.

В клиентской библиотеке токен разработчика указывается ключом api.googleads.developerToken в файле ads.properties .

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

Для авторизации пользователей учетных записей Google с доступом к аккаунтам Google Ads необходимо предоставить набор учетных данных 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

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

поток учетных записей сервиса

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

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

api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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

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

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

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

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

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

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

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

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

Добавьте следующее в файл ads.properties :

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

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

Что произойдет, если пользователь управляет несколькими учетными записями?

Нередко пользователь управляет несколькими аккаунтами Google Ads, либо напрямую, либо через аккаунт менеджера Google Ads. Клиентская библиотека Java предоставляет следующие примеры кода, иллюстрирующие обработку таких случаев.

  1. Пример кода GetAccountHierarchy демонстрирует, как получить список всех аккаунтов, находящихся в учетной записи менеджера Google Ads.
  2. Пример кода ListAccessibleCustomers показывает, как получить список всех учетных записей, к которым пользователь имеет прямой доступ. Затем эти учетные записи можно использовать в качестве допустимых значений для параметра LoginCustomerId .

Учетные данные приложения по умолчанию

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

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

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

Чтобы использовать учетные данные приложения по умолчанию, установите параметр api.googleads.useApplicationDefaultCredentials в true в файле ads.properties . При использовании учетных данных приложения по умолчанию идентификатор клиента, секретный ключ клиента и токен обновления указывать не следует.