Сервисные аккаунты

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

Учётная запись сервиса — это учётная запись, принадлежащая вашему приложению, а не отдельному конечному пользователю. Учётные записи сервисов обеспечивают межсерверное взаимодействие между веб-приложением и сервисом Google. Ваше приложение обращается к API Google от имени учётной записи сервиса, поэтому пользователи не участвуют в этом напрямую.

Учетные записи служб используют протокол OAuth 2.0, не требующий человеческой авторизации. Вместо этого используется файл ключа, к которому имеет доступ только ваше приложение.

Использование учетных записей служб обеспечивает два ключевых преимущества:

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

  • Поток утверждений OAuth 2.0 позволяет вашему приложению выдавать себя за других пользователей при необходимости.

Существует два способа авторизации с использованием учетных записей служб: напрямую или с использованием имперсонализации (не рекомендуется).

[Рекомендуется] Авторизация с прямым доступом к аккаунту

В этом варианте вы предоставляете учетной записи сервиса прямой доступ к вашему аккаунту Google Ads.

Настройка доступа к учетной записи

  1. Начните с создания учетной записи службы и учетных данных .

    Загрузите ключ учетной записи службы в формате JSON и запишите идентификатор учетной записи службы и адрес электронной почты.

  2. Войдите в свой аккаунт Google Ads как администратор. Перейдите в раздел «Администрирование» > «Доступ и безопасность» .

  3. Нажмите кнопку + на вкладке Пользователи .

  4. Введите адрес электронной почты учётной записи службы в поле «Электронная почта» . Выберите соответствующий уровень доступа и нажмите кнопку « Добавить учётную запись» . Обратите внимание, что уровни доступа «Электронная почта» и «Администратор» не поддерживаются для учётных записей служб.

  5. Учетной записи сервиса предоставлен доступ.

Конфигурация клиентской библиотеки

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

Ява

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

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

Дополнительные сведения см. в руководстве по настройке .

.СЕТЬ

Настройте следующие ключи в файлах App.config / Web.config . Дополнительные сведения см. в руководстве по настройке .

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

Питон

Укажите путь к JSON-файлу закрытого ключа в вашей конфигурации. Если вы используете google-ads.yaml file , строку YAML или dict , добавьте следующее:

json_key_file_path: JSON_KEY_FILE_PATH

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

Настройте следующие ключи в файле google_ads_php.ini . Подробнее см. в руководстве по настройке .

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Руби

Настройте следующие ключи в файле google_ads_config.rb .

c.keyfile = 'JSON_KEY_FILE_PATH'

Перл

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

jsonKeyFilePath=JSON_KEY_FILE_PATH

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

[Не рекомендуется] Авторизация с использованием имперсонации

В этом случае вы выдаёте себя за пользователя, имеющего доступ к вашему аккаунту Google Ads, используя сервисный аккаунт. Этот подход работает только для клиентов Google Workspace. Сервисный аккаунт может выдавать себя за пользователей (адреса электронной почты) только в том же Google Workspace .

Предпосылки

  • Домен Google Workspace , которым вы владеете, например mydomain.com или mybusiness.com

  • Токен разработчика API Google Ads и, при необходимости, тестовый аккаунт

  • Клиентская библиотека для используемого вами языка

  • Проект Google API Console, настроенный для API Google Ads

  • Пользователь Google Ads с разрешениями на доступ к аккаунту Google Ads, к которому вы хотите получить доступ.

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

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

  1. Начните с создания учетной записи службы и учетных данных .

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

  2. Сообщите администратору домена идентификатор учетной записи службы и область действия API Google Ads ( https://www.googleapis.com/auth/adwords ).

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

  3. Если вы являетесь администратором домена, следуйте инструкциям справочного центра .

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

Конфигурация клиентской библиотеки

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

Ява

Задайте путь к JSON-файлу закрытого ключа и идентификатор делегируемой учётной записи в вашей конфигурации. Если вы используете файл ads.properties , добавьте следующее:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

Дополнительные сведения см. в руководстве по настройке .

.СЕТЬ

Настройте следующие ключи в файлах App.config / Web.config . Дополнительные сведения см. в руководстве по настройке.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

Питон

Укажите путь к JSON-файлу закрытого ключа и адрес электронной почты, указанный от имени пользователя, в вашей конфигурации. Если вы используете google-ads.yaml file , строку YAML или dict , добавьте следующее:

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

Настройте следующие ключи в файле google_ads_php.ini . Подробнее см. в руководстве по настройке .

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

Руби

Настройте следующие ключи в файле google_ads_config.rb .

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

Перл

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

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

Проблемы безопасности

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

Ещё одна хорошая практика — предоставлять учётным записям служб доступ только к минимально необходимому набору API. Это превентивная мера, позволяющая ограничить объём данных, к которым злоумышленник может получить доступ в случае компрометации файла ключей учётной записи службы.