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

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

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

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

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

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

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

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

Это рекомендуемый рабочий процесс, если он не требует участия человека. Для этого нужно добавить сервисный аккаунт в аккаунт Google Рекламы. После этого приложение сможет использовать учетные данные сервисного аккаунта для управления аккаунтом Google Рекламы пользователя. Чтобы настроить это, создайте и скачайте файл ключа JSON в Google Cloud Console, а затем скопируйте google_ads_config.rb в домашний каталог и измените его, указав местоположение файла ключа сервисного аккаунта (и, при необходимости, адрес электронной почты пользователя, которого нужно имитировать при использовании делегирования на уровне домена Google Workspace):

# 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'
# Optional unless using Google Workspace domain-wide delegation:
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"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

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

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

Вы также можете использовать gem-файл googleauth, чтобы создать учетные данные сервисного аккаунта и передать credentials.updater_proc в config.authentication:

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 = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

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

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

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

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

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

# 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_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.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

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

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

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

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

# 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 to 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_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.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 Рекламы от его имени. Этот пример кода можно использовать в качестве справочного материала при создании приложений для ПК, требующих аутентификации пользователей.

Управление несколькими аккаунтами

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

В примере кода GetAccountHierarchy показано, как получить список всех аккаунтов, связанных с управляющим аккаунтом Google Рекламы.
В примере кода ListAccessibleCustomers показано, как получить список всех аккаунтов, к которым у пользователя есть прямой доступ. Эти аккаунты можно использовать в качестве допустимых значений для параметра login_customer_id.

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

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

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

Для Google Ads API убедитесь, что учетные данные по умолчанию для вашего приложения могут получить доступ к области действия 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:

# 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_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

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

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # 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 client_id, client_secret, or refresh_token here.
end

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