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

Как и другие 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. Чтобы настроить это, создайте и загрузите JSON-файл ключа в Google Cloud Console, затем скопируйте google_ads_config.rb в свой домашний каталог и измените его, указав расположение файла ключа сервисного аккаунта и адрес электронной почты пользователя, от имени которого он будет действовать:

  # You can also authenticate using a service account. If "keyfile" is
  # specified below, then service account authentication will be assumed and
  # the above authentication fields ignored. Read more about service account
  # authentication here:
  # https://developers.google.com/google-ads/api/docs/oauth/service-accounts
  # c.keyfile = 'path/to/keyfile.json'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Если вы предпочитаете не хранить эту информацию в файле и предпочитаете использовать переменные среды, вы можете установить GOOGLE_ADS_JSON_KEY_FILE_PATH и GOOGLE_ADS_IMPERSONATED_EMAIL соответственно.

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Вы также можете передавать информацию программно во время выполнения, используя gem-пакет googleauth для создания учетных данных из JSON-файла учетной записи службы:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file
key_file = "/path/to/your/service-account-key.json"

# Define the scopes needed for the Google Ads API
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials
credentials = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

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

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

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

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

Учетные данные OAuth 2.0 можно настроить для Ruby, скопировав файл google_ads_config.rb в свой домашний каталог и изменив его, включив в него токен разработчика, идентификатор клиента, секретный код клиента и токен обновления:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

Клиент автоматически прочитает файл конфигурации из домашнего каталога, если он создан без аргументов:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

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

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Если вы предпочитаете не хранить эту информацию в файле и предпочитаете использовать переменные среды, вы можете задать каждую из них:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Вы также можете передать информацию программно во время выполнения:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

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

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

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

Мы рекомендуем использовать файл конфигурации. Скопируйте файл google_ads_config.rb в свой домашний каталог и измените его, добавив токен разработчика, идентификатор клиента, секретный код клиента, токен обновления и идентификатор клиента:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

  # Required for manager accounts only: Specify the login customer ID used to
  # authenticate API calls. This will be the customer ID of the authenticated
  # manager account. If you need to use different values for this field, then
  # make sure fetch a new copy of the service after each time you change the
  # value.
  # c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

Клиент автоматически прочитает файл конфигурации из домашнего каталога, если он создан без аргументов: 

client = Google::Ads::GoogleAds::GoogleAdsClient.new

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

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Если вы предпочитаете не хранить эту информацию в файле и предпочитаете использовать переменные среды, вы можете задать каждую из них: 

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

Вы также можете передать информацию программно во время выполнения: 

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

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

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

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

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

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

Клиентская библиотека Ruby также поддерживает аутентификацию с использованием учётных данных приложения по умолчанию (ADC) . Она позволяет задать учётные данные по умолчанию для вашего приложения без необходимости настройки данных OAuth 2.0 в конфигурации приложения.

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

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

Чтобы использовать учетные данные приложения по умолчанию, мы рекомендуем использовать инструмент командной строки Google Cloud и выполнить аутентификацию для ADC: 

gcloud auth application-default login

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

Мы рекомендуем использовать файл конфигурации. Скопируйте файл google_ads_config.rb в домашний каталог, добавьте токен разработчика и установите для use_application_default_credentials значение true: 

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # You can also authenticate using Application Default Credentials (ADC)
  # To understand how ADC discovers credentials in a given environment,
  # see: https://developers.google.com/identity/protocols/application-default-credentials.
  c.use_application_default_credentials = true

Если вы предпочитаете не хранить эту информацию в файле и предпочитаете использовать переменные среды, вы можете установить GOOGLE_ADS_DEVELOPER_TOKEN и GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS : 

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Вы также можете передать информацию программно во время выполнения. При инициализации клиента в коде Ruby не указывайте явные учётные данные OAuth2. Библиотека автоматически определит и использует учётные данные, настроенные с помощью инструмента командной строки Google Cloud. Вам всё равно потребуется указать свой токен разработчика. 

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = "YOUR_LOGIN_CUSTOMER_ID"

  # Do NOT include oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

Дополнительную информацию о доступных параметрах настройки клиентской библиотеки Ruby см. на странице конфигурации .