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

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

Понимание модели доступа к Google Ads

Для эффективной работы с API Google Ads необходимо понимать, как работает модель доступа Google Ads. Рекомендуем ознакомиться с руководством по модели доступа Google Ads .

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

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

Поток учетной записи службы

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

Вот как настроить OAuth2 для доступа к API, используя собственные учетные данные с учетной записью службы в клиентской библиотеке Perl:

  1. Создайте учетные данные OAuth2:

    Следуйте инструкциям по созданию учетной записи службы и файла *.JSON .

  2. Настройте клиентскую библиотеку:

    Укажите путь к JSON-файлу закрытого ключа в настройках. Если вы используете файл googleads.properties , добавьте следующее:

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH

    Если вы используете переменные среды, добавьте следующее в конфигурацию или среду Bash:

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH

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

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

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

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

Следующие шаги запускают интерактивный пример кода, который затем требует от вас ввода данных.

  1. В терминале запустите пример generate_user_credentials.pl из каталога examples . Вы можете изменить значения INSERT_XXX_HERE в примере перед запуском или использовать аргументы командной строки -client_id для идентификатора клиента и -client_secret для секретного значения клиента.

    perl generate_user_credentials.pl -client_id {client_id} -client_secret {client_secret}

  2. В этом примере кода вам предлагается перейти по URL-адресу, по которому необходимо разрешить приложению доступ к вашей учетной записи Google Ads от вашего имени.

    Paste this url in your browser:
https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline&client_id=...

    Перейдите по URL-адресу в приватном сеансе браузера или в окне в режиме инкогнито. Войдите в систему, используя учётную запись Google, которую вы используете для доступа к Google Рекламе. Обычно это учётная запись электронной почты с доступом к управляющему аккаунту Google Рекламы, содержащему все необходимые вам аккаунты в рамках его иерархии. Нажмите «Продолжить» на экране согласия OAuth 2.0.

    Экран согласия OAuth 2.0

    Вы будете перенаправлены на страницу с сообщением об успешной авторизации.

    Authorization code was successfully retrieved.

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

    Replace the following keys and values in your googleads.properties configuration file:

clientId==***********************apps.googleusercontent.com
clientSecret=****
refreshToken=****

  4. Нажмите Ctrl + C чтобы завершить процесс. Затем скопируйте сгенерированный токен обновления вместе с идентификатором и секретным ключом клиента в файл googleads.properties или сохраните его в другом месте для использования при создании экземпляра библиотеки во время выполнения.

Библиотеку можно инициализировать, используя учетные данные OAuth 2.0 пользователя, установив следующее в googleads.properties :

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

В качестве альтернативы можно использовать переменные среды:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

Многопользовательский поток аутентификации

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

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

Конфигурация использования полученных учетных данных такая же, как и для потока аутентификации одного пользователя:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

В качестве альтернативы используйте переменные окружения: 

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

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

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

  1. Пример get_account_hierarchy.pl показывает, как получить список всех аккаунтов в управляющем аккаунте Google Ads.
  2. Пример list_accessible_customers.pl показывает, как получить список всех учётных записей, к которым у пользователя есть прямой доступ. Эти учётные записи затем можно использовать в качестве допустимых значений параметра LoginCustomerId в файле googleads.properties или переменной среды GOOGLE_ADS_LOGIN_CUSTOMER_ID .