Конфигурация

Вы можете настроить клиентскую библиотеку Python с помощью YAML-файла, переменных среды, строки YAML или dict.

Конфигурация аутентификации

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

Конфигурация с помощью файла YAML

При инициализации клиента можно указать файл YAML, содержащий необходимую информацию для отправки запросов к Google Ads API. Этот файл используется при инициализации клиента с помощью метода load_from_storage. Самый простой способ создать этот файл – скопировать пример google-ads.yaml из репозитория GitHub и изменить его, добавив свои учетные данные, в том числе токен обновления, идентификатор клиента и секрет клиента.

Если вы не укажете путь, библиотека будет искать файл в каталоге $HOME:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

Чтобы указать местоположение файла google-ads.yaml, можно передать путь в виде строки в метод при его вызове:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Вы также можете указать путь, задав определенную переменную среды:

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

Если указаны оба значения (путь передается в метод и присутствует переменная среды), библиотека отдает приоритет пути, переданному в метод.

Настройка с помощью переменных среды

Вы можете хранить все настройки клиента в виде переменных среды, которые считываются при использовании метода load_from_env клиента. Переменные среды должны иметь те же названия, что и в файле google-ads.yaml, но должны быть написаны прописными буквами и иметь префикс пространства имен GOOGLE_ADS_. Например, client_id следует хранить как GOOGLE_ADS_CLIENT_ID.

Переменные среды обычно определяются в файле конфигурации bash, например в файле .bashrc или .bash_profile, расположенном в каталоге $HOME. Их также можно задать с помощью командной строки.

Вот основные шаги по определению переменной среды с помощью файла .bashrc в терминале:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

Переменные среды также можно задать в экземпляре терминала непосредственно из командной строки:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

Метод load_from_env загружает данные конфигурации из атрибута environ встроенного модуля os языка Python. Например: os.environ["GOOGLE_ADS_CLIENT_ID"]

Вот пример инициализации экземпляра клиента с конфигурацией из переменных среды:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Чтобы настроить logging с помощью переменных среды, значение конфигурации должно быть объектом JSON, структура которого соответствует ключам YAML в образце файла конфигурации google-ads.yaml.

Вот пример того, как это можно сделать с помощью файла .bashrc:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Важно! Если при вызове метода load_from_env задана переменная среды GOOGLE_ADS_CONFIGURATION_FILE_PATH, то значения конфигурации извлекаются из файла google-ads.yaml, расположенного по указанному пути, а не из переменных среды, описанных выше.

Конфигурация с помощью строки YAML

Если вы прочитали файл YAML в память, вы можете передать его клиенту напрямую при инициализации. Для этого используйте метод load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Конфигурация с помощью dict

Вы можете передать dict непосредственно в метод load_from_dict. Пример:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Поля конфигурации

Конфигурация клиентской библиотеки поддерживает следующие поля:

Аутентификация

Используйте только одну из этих групп полей в зависимости от того, какой подход к аутентификации вы используете:

  • Однопользовательский аккаунт с учетными данными приложения по умолчанию (документация).
    • use_application_default_credentials – нужно ли библиотеке использовать учетные данные приложения по умолчанию для аутентификации (поддерживается в google-ads v28.3.0 и более поздних версиях).
  • Для одного пользователя с токенами OAuth (документация)
    • client_id – идентификатор клиента OAuth.
    • client_secret – секретный код клиента OAuth.
    • refresh_token – токен обновления OAuth.
  • Аккаунт сервиса (документация)
    • json_key_file_path: путь к локальному файлу закрытого ключа. Используется для аутентификации с помощью сервисного аккаунта.
    • impersonated_email – необязательный адрес электронной почты аккаунта, который нужно имитировать при использовании делегирования доступа на уровне домена Google Workspace.

Поведение библиотеки

Эти поля определяют поведение библиотеки:

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

Переменные среды

Чтобы настроить библиотеку с помощью переменных среды, используйте следующие команды:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (поддерживается в v28.3.0 и более поздних версиях)

Настройка журнала

Поля журнала, которые находятся под полем конфигурации logging, извлекаются непосредственно из встроенного модуля logging.config, поскольку библиотека передает все поля из пространства имен logging непосредственно в метод logging.config.dictConfig. Подробную информацию вы найдете в руководстве по ведению журналов.

  • version – целое число, представляющее версию схемы.
  • disable_existing_loggers – нужно ли отключить регистраторы, настроенные в других частях приложения.
  • formatters – словари, определяющие разные типы форматирования.
  • handlers – словари, определяющие разные обработчики, которые управляют тем, куда записываются журналы и какие форматировщики следует использовать.
  • loggers: словари, определяющие разные типы регистраторов, которые включают обработчик и уровень регистрации.