Wiadomości protokołu Protobuf

Wersja 14.0.0 biblioteki klienta języka Python wprowadza nowy wymagany parametr konfiguracji. o nazwie use_proto_plus, która określa, czy biblioteka ma zwrócić wiadomości Proto-plus lub wiadomości protokołu Protobuf. Więcej informacji: sposób ustawienia tego parametru znajdziesz w dokumentacji konfiguracji.

W tej sekcji opisujemy wpływ wyboru typów komponentów na wydajność dlatego zalecamy ich zapoznanie się z dostępnych opcji, aby można było podjąć świadomą decyzję. Jeśli jednak chcesz uaktualnić do wersji 14.0.0 bez wprowadzania zmian w kodzie, można ustawić Z use_proto_plus na True, by uniknąć zmian w interfejsie.

Komunikaty protokołu Plus a komunikaty protokołu protobuf

W wersji 10.0.0 biblioteka klienta języka Python została przeniesiona do nowego generatora kodu zintegrowany potok protoplus jako sposób na usprawnienie z ergonomią interfejsu komunikatów Protobuf dzięki temu, że zachowują się one takich jak natywne obiekty Pythona. Zaletą tego ulepszenia jest to, że proto-plus wiąże się z przekroczeniem wydajności.

Skuteczność Protoplus

Jedną z głównych zalet protokołu Protoplus jest konwertowanie protobufów wiadomości i dobrze znanych typów natywne typy Pythona z użyciem procesu zwanego typem organizowanie kampanii.

Organizowanie ma miejsce, gdy uzyskano dostęp do pola w instancji wiadomości proto+, zwłaszcza gdy pole jest odczytywane lub ustawione, na przykład w protobufie. definicja:

syntax = "proto3";

message Dog {
  string name = 1;
}

Gdy ta definicja zostanie przekonwertowana na klasę proto-plus, będzie to wyglądać tak: podobny do tego:

import proto

class Dog(proto.Message):
    name = proto.Field(proto.STRING, number=1)

Możesz wtedy zainicjować klasę Dog i uzyskać dostęp do jej pola name w taki sam sposób jak dowolny inny obiekt w Pythonie:

dog = Dog()
dog.name = "Scruffy"
print(dog.name)

Podczas odczytywania i konfigurowania pola name wartość jest konwertowana z wartości natywnej Pythona str na typ string, więc że wartość jest zgodna ze środowiskiem wykonawczym protokołu.

W analizie przeprowadzonej od czasu wydania wersji 10.0.0 stwierdziliśmy, Ustaliliśmy, że czas poświęcony na tego typu konwersje na wydajność. Użytkownicy powinni mieć możliwość korzystania z protokołu Protobuf. wiadomości.

Przypadki użycia wiadomości protokołu Proto+ i Protobuf

Przypadki użycia wiadomości Proto+

Protoplus ma wiele ulepszeń w porównaniu do komunikatów Protobuf, więc idealnie nadają się do pisania łatwego w utrzymaniu i czytelnego kodu. Narażają się lub natywne obiekty Pythona, są łatwiejsze w użyciu i zrozumieniu.

Przypadki użycia wiadomości buforów protokołu

Używaj buforów protokołu w przypadkach użycia, w których liczy się wydajność, zwłaszcza w aplikacjach muszą szybko przetwarzać duże raporty lub tworzyć mutacje za pomocą funkcji dla wielu operacji, na przykład przy użyciu BatchJobService lub OfflineUserDataJobService

Dynamiczna zmiana typów wiadomości

Po wybraniu typu wiadomości odpowiedniego dla Twojej aplikacji możesz zobaczyć musisz użyć drugiego typu w określonym przepływie pracy. W tym przypadku jest to można łatwo przełączać się między nimi dynamicznie za pomocą narzędzi oferowanych przez z biblioteką klienta. Użyj tej samej klasy wiadomości w polu Dog:

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 komunikatów buforów protokołu

Interfejs Proto+ jest opisany w , ale tutaj podkreślimy kluczowe różnice, które wpływają na typowe przypadki użycia klienta Google Ads bibliotece.

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 pola

Metoda pomocnicza maski pola udostępniona przez Interfejs api-core służy do korzystania z protokołu protobuf instancji wiadomości. Dlatego gdy używasz wiadomości protoplus, przekonwertuj je na protobuf wiadomości przeznaczone do użycia z pomocą:

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 protokołu Plus są instancjami natywnymi w Pythonie typ enum, więc dziedziczenie kilku wygodnych metod.

Pobieranie typu wyliczenia

Gdy używasz metody GoogleAdsClient.get_type do pobierania wyliczeń, wiadomości mogą się nieznacznie różnić w zależności od tego, wiadomości protokołu protoplus lub 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 GoogleAdsClient instancji ze spójnym interfejsem niezależnie od tego, typ wiadomości, której używasz:

val = client.enums.CampaignStatusEnum.PAUSED

Pobieranie wartości wyliczenia

Czasami przydaje się znajomość wartości lub identyfikatora pola danego wyliczenia dla argumentu przykład PAUSED na 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
# To read the value of campaign status
print(status_enum.CampaignStatus.Value(campaign.status))

Pobieranie nazwy enum

Czasami dobrze jest znać nazwę pola wyliczenia. Na przykład, gdy odczytując obiekty z interfejsu API, warto wiedzieć, jaki stan kampanii ma int 3 odpowiada:

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
status_enum.CampaignStatus.Name(campaign.status)

Pola powtarzane

Zgodnie z opisem w proto-plus dokumenty, pola powtarzane są zasadniczo równoważne z listami typowymi, co oznacza, że działa prawie tak samo jak list.

Dołączam do powtarzających się pól skalarnych

Podczas dodawania wartości do powtarzających się wartości skalarnych type, np. string lub int64, interfejs jest taki sam niezależnie od komunikatu. typ:

Wiadomości Proto Plus

ad.final_urls.append("https://www.example.com")

Komunikaty Protobuf

ad.final_urls.append("https://www.example.com")

Obejmuje to również 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 skalarnem , zachowanie podczas dodawania pola powtarzane są 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 przypisać listy do 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 wystąpienie wiadomości zawiera informacji lub ma ustawione dowolne ze swoich pól.

Wiadomości Proto Plus

# When using proto-plus messages you can simply check the message for
# truthiness.
is_empty = bool(campaign)
is_empty = not campaign

Komunikaty Protobuf

is_empty = campaign.ByteSize() == 0

Kopia wiadomości

W przypadku wiadomości protokołu Protoplus i protokołu protobuf zalecamy użycie funkcji copy_from metody pomocniczej 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 Twojego typu wiadomości. Wystarczy skopiować pustą wiadomość w polu w związku z naruszeniem naszych przepisów. Zobacz sekcję Kopia wiadomości i Pusta wiadomość Przewodnik po polach. Oto przykład, aby ustawić puste pole wiadomości:

client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))

Nazwy pól będące zarezerwowanymi słowami

Jeśli używasz wiadomości Proto Plus, nazwy pól automatycznie wyświetlają się z dodanym podkreślenie na końcu, jeśli nazwa jest też słowem zarezerwowanym w Pythonie. Oto przykład pracy z instancją Asset:

asset = client.get_type("Asset")
asset.type_ = client.enums.AssetTypeEnum.IMAGE

Pełna lista zarezerwowanych nazwy jest skonstruowany w gapic generatora. Jest taka możliwość dostęp automatycznie.

Najpierw zainstaluj moduł:

python -m pip install gapic-generator

Następnie w REPL lub skrypcie w Pythonie:

import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)

Obecność pól

Pola instancji wiadomości buforów protokołu mają wartości domyślne, więc zawsze można łatwo sprawdzić, 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")

Protobuf Message interfejsu klasy ma metodę HasField, która określa, czy pole na wiadomość została ustawiona, nawet jeśli ma wartość domyślną.

Metody komunikatów buforów protokołu

Interfejs komunikatu buforowania protokołu zawiera kilka wygodnych metod, które nie są część interfejsu Proto-plus; ale dostęp do nich można łatwo uzyskać, skonwertowanie komunikatu protoplus na jego odpowiednik w formacie protobuf:

# Accessing the ListFields method
protobuf_campaign = util.convert_protobuf_to_proto_plus(campaign)
print(campaign.ListFields())

# Accessing the Clear method
protobuf_campaign = util.convert_protobuf_to_proto_plus(campaign)
print(campaign.Clear())

Śledzenie problemów

Jeśli masz pytania dotyczące tych zmian lub problemów z migracją do wersji 14.0.0 biblioteki, prześlij na naszej trackera.