Получение ссылок на все классы proto, необходимые для использования API в Python, может быть многословным и требует от вас глубокого понимания API или частого переключения контекста для ссылки на прототипы или документацию.
Методы get_service и get_type клиента
Эти два метода получения позволяют извлекать любой объект сервиса или типа в API. Метод get_service используется для получения клиентов сервиса. get_type используется для всех остальных объектов. Классы клиентских сервисов определяются в коде по пути версии google/ads/googleads/v*/services/, а все типы – по различным категориям объектов google/ads/googleads/v*/common|enums|errors|resources|services/types/. Весь код в каталоге версии генерируется, поэтому рекомендуется использовать эти методы, а не импортировать объекты напрямую, на случай если структура базы кода изменится.
В примере ниже показано, как использовать метод get_service, чтобы получить экземпляр клиента GoogleAdsService (или асинхронный GoogleAdsServiceAsyncClient в google-ads v28.4.0 и более поздних версиях, передав is_async=True).
from google.ads.googleads.client import GoogleAdsClient
# "load_from_storage" loads your API credentials from disk so they
# can be used for service initialization. Providing the optional `version`
# parameter means that the v26 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v26")
googleads_service = client.get_service("GoogleAdsService")
# Supported in google-ads v28.4.0 and later: retrieve an async service client.
googleads_async_service = client.get_service("GoogleAdsService", is_async=True)
В примере ниже показано, как использовать метод get_type, чтобы получить экземпляр Campaign:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v26")
campaign = client.get_type("Campaign")
Перечисления
Для получения перечислений можно использовать метод get_type, но у каждого экземпляра GoogleAdsClient также есть атрибут enums, который динамически загружает перечисления с помощью того же механизма, что и метод get_type. Этот интерфейс проще и понятнее, чем get_type:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v26")
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
Поля объектов Proto, которые являются перечислениями, представлены в Python встроенным типом enum. Это означает, что вы можете прочитать значение элемента напрямую. Работа с экземпляром campaign из предыдущего примера в Python REPL:
>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3
Иногда полезно знать название поля, которое соответствует значению перечисления. Вы можете получить доступ к этой информации с помощью атрибута name:
>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>
Взаимодействие с перечислениями зависит от того, какое значение задано для параметра use_proto_plus: true или false. Подробную информацию об этих интерфейсах можно найти в документации по сообщениям protobuf.
Управление версиями
Одновременно поддерживается несколько версий API. Хотя v26 – это последняя версия, более ранние версии по-прежнему доступны, пока не будут выведены из эксплуатации. Библиотека включает отдельные классы сообщений proto, которые соответствуют каждой активной версии API. Чтобы получить доступ к классу сообщений для определенной версии, укажите параметр ключевого слова version при инициализации клиента, чтобы он всегда возвращал экземпляр из этой версии:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v26")
# The Campaign instance will be from the v26 version of the API.
campaign = client.get_type("Campaign")
Если вы не укажете version при инициализации клиента, то можете указать версию для каждого вызова при вызове методов get_service и get_type (обратите внимание, что если version задан при инициализации GoogleAdsClient, он переопределяет любой аргумент version, переданный в get_service или get_type):
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()
# This loads the v26 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v26"
)
# This loads a specific supported API version (such as v23) of a Campaign.
campaign = client.get_type("Campaign", version="v23")
Если параметр ключевого слова version не указан, библиотека по умолчанию использует самую высокую версию API, поддерживаемую установленным пакетом google-ads ("v26" в последнем выпуске). Обратите внимание, что для доступа к дополнительным выпускам API (например, v25.1) используется строка основной версии (version="v25"). Обновленный список последних и других доступных версий можно найти в левой части раздела навигации в документации по API.