Pobieranie odwołań do wszystkich klas proto wymaganych do korzystania z interfejsu API w Pythonie może być złożone i wymagać wrodzonej znajomości interfejsu API lub częstego przełączania kontekstu w celu odwoływania się do plików proto lub dokumentacji.
Metody get_service i get_type klienta
Te 2 metody pobierania umożliwiają uzyskanie dostępu do dowolnej usługi lub obiektu typu w interfejsie API. Metoda get_service służy do pobierania klientów usług. get_type jest używany w przypadku każdego innego obiektu. Klasy klientów usług są zdefiniowane w kodzie w ścieżce wersji google/ads/googleads/v*/services/, a wszystkie typy są zdefiniowane w różnych kategoriach obiektów google/ads/googleads/v*/common|enums|errors|resources|services/types/. Cały kod w katalogu wersji jest generowany, dlatego zamiast bezpośrednio importować obiekty, warto używać tych metod na wypadek zmiany struktury bazy kodu.
W przykładzie poniżej pokazujemy, jak za pomocą metody get_service pobrać instancję klienta GoogleAdsService (lub asynchroniczną GoogleAdsServiceAsyncClient w google-ads v28.4.0 i później przekazującą 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)
Poniższy przykład pokazuje, jak użyć metody get_type, aby pobrać instancję Campaign:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
campaign = client.get_type("Campaign")
Wartości w polu enum
Chociaż do pobierania wyliczeń możesz używać metody get_type, każda instancja GoogleAdsClient ma też atrybut enums, który dynamicznie wczytuje wyliczenia przy użyciu tego samego mechanizmu co metoda get_type. Ten interfejs jest prostszy i łatwiejszy do odczytania niż w przypadku używania 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
Pola obiektów protokołu, które są wyliczeniami, są reprezentowane w Pythonie przez wbudowany typ enum. Oznacza to, że możesz bezpośrednio odczytać wartość elementu. Praca z instancją campaign z poprzedniego przykładu w Python REPL:
>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3
Czasami warto znać nazwę pola odpowiadającego wartości wyliczeniowej. Dostęp do tych informacji możesz uzyskać za pomocą atrybutu name:
>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>
Sposób interakcji z wyliczeniami zależy od tego, czy konfiguracja
use_proto_plus jest ustawiona na true czy false. Szczegółowe informacje o tych 2 interfejsach znajdziesz w dokumentacji wiadomości protobuf.
Obsługa wersji
Jednocześnie utrzymywanych jest kilka wersji interfejsu API. Chociaż v25 to najnowsza wersja, starsze wersje są nadal dostępne do czasu ich wyłączenia. Biblioteka zawiera osobne klasy wiadomości protokołu, które odpowiadają każdej aktywnej wersji interfejsu API. Aby uzyskać dostęp do klasy wiadomości w określonej wersji, podczas inicjowania klienta podaj parametr słowa kluczowego version, aby zawsze zwracał instancję z danej wersji:
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")
Jeśli podczas inicjowania klienta nie określisz parametru version, możesz określić wersję dla każdego wywołania podczas wywoływania metod get_service i get_type (pamiętaj, że jeśli podczas inicjowania parametru GoogleAdsClient ustawisz parametr version, zastąpi on każdy argument version przekazany do metody get_service lub 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")
Jeśli nie podasz parametru słowa kluczowego version, biblioteka domyślnie użyje najwyższej wersji interfejsu API obsługiwanej przez zainstalowany pakiet google-ads ("v25" w najnowszej wersji). Pamiętaj, że do wersji podrzędnych interfejsu API (np. v25.1) uzyskuje się dostęp za pomocą ciągu znaków wersji głównej (version="v25"). Zaktualizowaną listę najnowszych i innych dostępnych wersji znajdziesz w sekcji nawigacji po lewej stronie dokumentacji API Reference.