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

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

Модель доступа в Google Рекламе

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

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

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

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

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

Ниже описано, как настроить OAuth2 для доступа к API с использованием собственных учетных данных с сервисным аккаунтом в клиентской библиотеке Perl.

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

    Следуйте инструкциям, чтобы создать сервисный аккаунт и JSON-файл ключа.

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

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

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
# Optional unless using Google Workspace domain-wide delegation:
impersonatedEmail=IMPERSONATED_EMAIL
loginCustomerId=LOGIN_CUSTOMER_ID

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=\
IMPERSONATED_EMAIL
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

    Подробнее о рабочем процессе с сервисным аккаунтом…

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

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

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

Ниже описано, как запустить интерактивный пример кода, в который нужно будет ввести данные.

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

    perl generate_user_credentials.pl \
  -client_id OAUTH_CLIENT_ID \
  -client_secret OAUTH_CLIENT_SECRET

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

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

    Перейдите по 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
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_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

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

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

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

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

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_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_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

Что делать, если у пользователя несколько аккаунтов?

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

  1. В примере get_account_hierarchy.pl показано, как получить список всех аккаунтов, связанных с управляющим аккаунтом Google Рекламы.
  2. В примере list_accessible_customers.pl показано, как получить список всех аккаунтов, к которым у пользователя есть прямой доступ. Затем эти аккаунты можно использовать в качестве допустимых значений для настройки loginCustomerId в файле googleads.properties или переменной среды GOOGLE_ADS_LOGIN_CUSTOMER_ID.