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

Как и другие 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 пользователя. Библиотека Python настраивается следующим образом:

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

    json_key_file_path: JSON_KEY_FILE_PATH

    Затем вызовите методы load_from_storage или load_from_string :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

  • Если вы используете dict для настройки библиотеки, включите следующую пару ключ-значение и вызовите метод load_from_dict , передав dict конфигурации:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "json_key_file_path": JSON_KEY_FILE_PATH
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    Затем вызовите метод load_from_env :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
  ```

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

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

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

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

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

  2. Пользователь запускает инструмент, такой как gcloud CLI или пример кода generate_user_credentials , чтобы авторизовать ваше приложение для управления всеми его аккаунтами Google Ads от его имени.

Библиотеку можно инициализировать, используя учетные данные пользователя OAuth 2.0 следующим образом:

При использовании инструмента командной строки gcloud (рекомендуется)

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

  2. Добавьте следующую конфигурацию в строку google-ads.yaml или YAML:

    use_application_default_credentials: true

    Затем вызовите метод load_from_storage или load_from_string :

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Если вы используете dict для настройки библиотеки, включите следующую пару ключ-значение и вызовите метод load_from_dict :

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "use_account_default_credentials": True
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true

    Затем вызовите метод load_from_env : 

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

При прямой обработке токенов OAuth

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

  2. Клонируйте клиентскую библиотеку Python на свой компьютер и перейдите в ее каталог: 

    $ git clone https://github.com/googleads/google-ads-python.git
$ cd google-ads-python

  3. Выполните пример, указав абсолютный путь к JSON-файлу, загруженному на шаге 1: 

    $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON

    После завершения на вашей консоли появится токен обновления. Скопируйте его и сохраните для следующего шага.

  4. Настройте библиотеку, добавив следующие параметры в выбранную вами конфигурацию:

    Добавьте следующую конфигурацию в строку google-ads.yaml или YAML: 

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    Затем вызовите метод load_from_storage или load_from_string : 

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Если вы используете dict для настройки библиотеки, включите следующие пары ключ-значение и вызовите метод load_from_dict : 

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
  "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
  "refresh_token": INSERT_REFRESH_TOKEN_HERE
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

    Затем вызовите метод load_from_env : 

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

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

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

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

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

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

Ручная аутентификация

Вы можете сгенерировать учётные данные авторизации любым способом и передать их GoogleAdsClient вручную, создав экземпляр класса клиента напрямую. Если создаваемый вами объект учётных данных является экземпляром google.auth.credentials.Credentials , вы можете передать его следующим образом: 

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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

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

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