Za pomocą parametru konfiguracji use_proto_plus możesz określić, czy biblioteka ma zwracać wiadomości proto-plus czy wiadomości protobuf. Szczegółowe informacje o tym, jak ustawić ten parametr, znajdziesz w dokumentacji konfiguracji.
W tej sekcji opisujemy wpływ każdej opcji na wydajność, aby ułatwić Ci wybór najlepszego podejścia do Twojej aplikacji.
Wiadomości proto-plus a wiadomości buforów protokołu
Potok generatora kodu integruje proto-plus, aby zwiększyć ergonomię interfejsu wiadomości protobuf, sprawiając, że zachowują się one bardziej jak standardowe obiekty Pythona. Oznacza to jednak, że używanie proto-plus wiąże się z obniżeniem wydajności.
Skuteczność proto-plus
Jedną z głównych zalet proto-plus jest to, że przekształca wiadomości protobuf i znane typy w wbudowane typy Pythona w procesie zwanym marshalizacją typów.
Marshaling występuje, gdy uzyskuje się dostęp do pola w instancji wiadomości proto-plus, a konkretnie wtedy, gdy pole jest odczytywane lub ustawiane, na przykład w definicji protobuf:
syntax = "proto3";
message Dog {
string name = 1;
}
Po przekształceniu tej definicji w klasę proto-plus będzie ona wyglądać tak:
import proto
class Dog(proto.Message):
name = proto.Field(proto.STRING, number=1)
Następnie możesz zainicjować klasę Dog i uzyskać dostęp do jej pola name tak jak w przypadku każdego innego obiektu Pythona:
dog = Dog()
dog.name = "Scruffy"
print(dog.name)
Podczas odczytywania i ustawiania pola name wartość jest konwertowana z wbudowanego typu Pythona str na typ string, aby była zgodna ze środowiskiem wykonawczym protokołu buforowania.
Czas poświęcony na wykonywanie tych konwersji typów ma wystarczająco duży wpływ na wydajność, aby na podstawie potrzeb aplikacji podjąć decyzję, czy używać wiadomości proto-plus czy protobuf.
Przypadki użycia wiadomości proto-plus i protobuf
- Przykłady użycia wiadomości Proto-Plus
- Proto-plus oferuje szereg ulepszeń ergonomicznych w porównaniu z wiadomościami protobuf, dzięki czemu idealnie nadaje się do pisania kodu, który jest łatwy w utrzymaniu i czytelny. Ponieważ udostępniają standardowe obiekty Pythona, są łatwiejsze w użyciu i zrozumieniu.
- Przykłady użycia wiadomości Protobuf
- Używaj protokołów buforowanych w przypadku zastosowań, w których wydajność jest kluczowa, zwłaszcza w aplikacjach, które muszą szybko przetwarzać duże raporty lub tworzyć żądania modyfikacji z dużą liczbą operacji, np. za pomocą
BatchJobServicelubOfflineUserDataJobService.
Dynamiczne przełączanie typów wiadomości
Po wybraniu odpowiedniego typu wiadomości dla aplikacji może się okazać, że w określonym przepływie pracy musisz użyć innego typu. W takim przypadku możesz dynamicznie przełączać się między tymi 2 rodzajami za pomocą narzędzi oferowanych przez bibliotekę klienta. Użyj tej samej klasy wiadomości Dog co wcześniej:
from google.ads.googleads import util
# Proto-plus message type
dog = Dog()
# Protobuf message type
dog = util.convert_proto_plus_to_protobuf(dog)
# Back to proto-plus message type
dog = util.convert_protobuf_to_proto_plus(dog)
Różnice w interfejsie wiadomości Protobuf
Interfejs proto-plus jest szczegółowo opisany, a w sekcjach poniżej znajdziesz najważniejsze różnice, które mają wpływ na typowe przypadki użycia biblioteki klienta Google Ads.
Serializacja bajtów
- Wiadomości Proto-plus
serialized = type(campaign).serialize(campaign) deserialized = type(campaign).deserialize(serialized)
- Komunikaty Protobuf
serialized = campaign.SerializeToString() deserialized = campaign.FromString(serialized)
Serializacja JSON
- Wiadomości Proto-plus
serialized = type(campaign).to_json(campaign) deserialized = type(campaign).from_json(serialized)
- Komunikaty Protobuf
from google.protobuf.json_format import MessageToJson, Parse serialized = MessageToJson(campaign) deserialized = Parse(serialized, campaign)
Maski pól
Metoda pomocnicza maski pola udostępniana przez api-core jest przeznaczona do używania instancji wiadomości protobuf. Jeśli używasz wiadomości proto-plus, przekonwertuj je na wiadomości protobuf, aby użyć funkcji pomocniczej:
- Wiadomości Proto-plus
from google.api_core.protobuf_helpers import field_mask campaign = client.get_type("Campaign") protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign) mask = field_mask(None, protobuf_campaign)
- Komunikaty Protobuf
from google.api_core.protobuf_helpers import field_mask campaign = client.get_type("Campaign") mask = field_mask(None, campaign)
Wartości w polu enum
Wyliczenia udostępniane przez wiadomości proto-plus są instancjami wbudowanego typu enum w Pythonie, dlatego dziedziczą wiele wygodnych metod.
Pobieranie typu wyliczeniowego
Gdy do pobierania wyliczeń używasz metody GoogleAdsClient.get_type, zwracane komunikaty różnią się nieznacznie w zależności od tego, czy używasz komunikatów proto-plus czy protobuf. Na przykład:
- Wiadomości Proto-plus
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
- Komunikaty Protobuf
val = client.get_type("CampaignStatusEnum").PAUSED
Aby ułatwić pobieranie wyliczeń, w przypadku instancji GoogleAdsClient dostępny jest atrybut wygody, który ma spójny interfejs niezależnie od używanego typu wiadomości:
val = client.enums.CampaignStatusEnum.PAUSED
Pobieranie wartości typu wyliczeniowego
Czasami warto znać wartość lub identyfikator pola danego wyliczenia, np. PAUSED w CampaignStatusEnum odpowiada 3:
- Wiadomości Proto-plus
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the value of campaign status print(campaign.status.value)
- Komunikaty Protobuf
campaign = client.get_type("Campaign") status_enum = client.enums.CampaignStatusEnum campaign.status = status_enum.PAUSED # Native protobuf enum fields already store the integer value (3): print(campaign.status) # Or look up the integer value from the enum name string: print(status_enum.CampaignStatus.Value("PAUSED"))
Pobieranie nazwy typu wyliczeniowego
Czasami warto znać nazwę pola wyliczeniowego. Na przykład podczas odczytywania obiektów z interfejsu API możesz chcieć wiedzieć, jakiemu stanowi kampanii odpowiada liczba całkowita 3:
- Wiadomości Proto-plus
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the name of campaign status print(campaign.status.name)
- Komunikaty Protobuf
campaign = client.get_type("Campaign") status_enum = client.enums.CampaignStatusEnum # Sets the campaign status to the int value for PAUSED campaign.status = status_enum.PAUSED # To read the name of campaign status print(status_enum.CampaignStatus.Name(campaign.status))
Pola powtarzane
Jak opisano w dokumentacji proto-plus, pola powtarzane są ogólnie odpowiednikiem list typowanych, co oznacza, że zachowują się niemal identycznie jak list.
Dołączanie wartości do powtarzanych pól skalarnych
Podczas dodawania wartości do powtarzanych pól typu skalarnego, np. pól string lub int64, interfejs jest taki sam niezależnie od typu wiadomości:
- Wiadomości Proto-plus
ad.final_urls.append("https://www.example.com")
- Komunikaty Protobuf
ad.final_urls.append("https://www.example.com")
Obejmuje to wszystkie inne popularne metody list, np. extend:
- Wiadomości Proto-plus
ad.final_urls.extend( ["https://www.example.com", "https://www.example.com/2"] )
- Komunikaty Protobuf
ad.final_urls.extend( ["https://www.example.com", "https://www.example.com/2"] )
Dołączanie typów wiadomości do pól powtarzanych
Jeśli pole powtarzane nie jest typu skalarnego, zachowanie podczas dodawania ich do pól powtarzanych jest nieco inne:
- Wiadomości Proto-plus
frequency_cap = client.get_type("FrequencyCapEntry") frequency_cap.cap = 100 campaign.frequency_caps.append(frequency_cap)
- Komunikaty Protobuf
# The add method initializes a message and adds it to the repeated field frequency_cap = campaign.frequency_caps.add() frequency_cap.cap = 100
Przypisywanie pól powtarzanych
Zarówno w przypadku skalarnych, jak i nieskalarnych pól powtarzanych możesz przypisywać listy do pola na różne sposoby:
- Wiadomości Proto-plus
# In proto-plus it's possible to use assignment. urls = ["https://www.example.com"] ad.final_urls = urls
- Komunikaty Protobuf
# Protobuf messages do not allow assignment, but you can replace the # existing list using slice syntax. urls = ["https://www.example.com"] ad.final_urls[:] = urls
Puste wiadomości
Czasami warto wiedzieć, czy instancja wiadomości zawiera jakiekolwiek informacje lub czy ma ustawione którekolwiek z pól.
- Wiadomości Proto-plus
# When using proto-plus messages you can check the message for truthiness. is_empty = not bool(campaign)
- Komunikaty Protobuf
is_empty = campaign.ByteSize() == 0
Treść wiadomości
W przypadku wiadomości proto-plus i protobuf użyj metody pomocniczej copy_from w GoogleAdsClient:
client.copy_from(campaign, other_campaign)
Puste pola wiadomości
Proces ustawiania pustych pól wiadomości jest taki sam niezależnie od typu wiadomości, którego używasz. Kopiujesz pustą wiadomość do odpowiedniego pola. Zapoznaj się z sekcją Treść wiadomości oraz przewodnikiem Puste pola wiadomości. Poniższy przykład pokazuje, jak ustawić puste pole wiadomości:
client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))
Nazwy pól, które są słowami zastrzeżonymi
W przypadku korzystania z wiadomości proto-plus nazwy pól automatycznie pojawiają się z podkreśleniem na końcu, jeśli nazwa jest również słowem zastrzeżonym w Pythonie. Poniższy przykład
pokazuje, jak pracować z instancją Asset:
asset = client.get_type("Asset")
asset.type_ = client.enums.AssetTypeEnum.IMAGE
Pełna lista zarezerwowanych nazw jest tworzona w module generatora gapic. Można do niej uzyskać dostęp również automatycznie.
Najpierw zainstaluj moduł:
python -m pip install gapic-generator
Następnie w interpreterze Python REPL lub skrypcie:
import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)
Obecność pola
Pola w instancjach wiadomości protobuf mają wartości domyślne, więc nie zawsze wiadomo, czy pole zostało ustawione.
- Wiadomości Proto-plus
# Use the "in" operator. has_field = "name" in campaign
- Komunikaty Protobuf
campaign = client.get_type("Campaign") # Determines whether "name" is set and not just an empty string. campaign.HasField("name")
Interfejs klasy protobuf Message ma metodę HasField, która określa, czy podrzędna wiadomość, pole oneof lub pole skalarne optional w wiadomości zostało ustawione, nawet jeśli zostało ustawione na wartość domyślną.
(Wywołanie HasField w przypadku pól skalarnych, które nie są opcjonalne, w proto3 powoduje błąd ValueError).
Metody wiadomości Protobuf
Interfejs wiadomości protobuf zawiera kilka metod ułatwiających pracę, które nie są częścią interfejsu proto-plus. Możesz jednak uzyskać do nich dostęp, konwertując wiadomość proto-plus na jej odpowiednik protobuf:
# Accessing the ListFields method
protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign)
print(protobuf_campaign.ListFields())
# Accessing the Clear method
protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign)
protobuf_campaign.Clear()
Śledzenie problemów
Jeśli masz pytania dotyczące tych zmian lub problemy z przejściem na najnowszą wersję biblioteki, zgłoś problem w narzędziu Issue Tracker.