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

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

Как и другие 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 Рекламы пользователя. Чтобы настроить его, создайте и скачайте 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

Вы также можете использовать гем 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.

Application Default Credentials

Клиентская библиотека 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 значение 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 можно найти на странице конфигурации.