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

Как и другие API Google, API Google Ads использует протокол OAuth 2.0 для аутентификации и авторизации. OAuth 2.0 позволяет клиентскому приложению API Google Ads получать доступ к аккаунту пользователя 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 Рекламы необходимо предоставить набор учётных данных OAuth 2.0. Тип требуемых учётных данных зависит от используемого протокола OAuth 2.0.

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

  • Поток учетной записи службы
  • Процесс аутентификации одного пользователя
  • Многопользовательский поток аутентификации

Подробную информацию о потоках OAuth API Google Ads см. в разделе «Обзор 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 . При использовании учётных данных приложения по умолчанию идентификатор клиента, секретный код клиента и токен обновления не должны быть заданы.