Получение ссылок на все классы протокола, необходимые для использования 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 v25 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v25")
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="v25")
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="v25")
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. v25 – последняя версия, но более ранние версии будут доступны до даты вывода из эксплуатации. Библиотека содержит отдельные классы сообщений протокола, соответствующие каждой активной версии API. Чтобы получить доступ к классу сообщений для определенной версии, укажите параметр ключевого слова version при инициализации клиента, чтобы он всегда возвращал экземпляр из этой версии:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
# The Campaign instance will be from the v25 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 v25 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v25"
)
# This loads a specific supported API version (such as v23) of a Campaign.
campaign = client.get_type("Campaign", version="v23")
Если параметр ключевого слова version не указан, библиотека по умолчанию использует самую высокую версию API, поддерживаемую установленным пакетом google-ads ("v25" в последнем выпуске). Обратите внимание, что доступ к второстепенным версиям API (например, v25.1) осуществляется с помощью строки основной версии (version="v25"). Актуальный список последних и других доступных версий можно найти в разделе навигации слева в справочной документации по API.