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

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

Разберитесь в модели доступа к рекламным объявлениям Google.

Для эффективной работы с 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 .