Messaggi Protobuf

La versione 14.0.0 della libreria client Python introduce un nuovo parametro di configurazione obbligatorio denominato use_proto_plus che specifica se vuoi che la libreria restituisca messaggi proto-plus o messaggi protobuf. Per maggiori dettagli su come impostare questo parametro, consulta la documentazione di configurazione.

Questa sezione descrive le implicazioni in termini di prestazioni della scelta dei tipi di messaggi da utilizzare. Pertanto, ti consigliamo di leggere e comprendere le opzioni per prendere una decisione consapevole. Tuttavia, se vuoi eseguire l'upgrade alla versione 14.0.0 senza apportare modifiche al codice, puoi impostare use_proto_plus su True per evitare di interrompere le modifiche all'interfaccia.

Messaggi Proto-plus e protobuf

Nella versione 10.0.0, la libreria client Python è stata migrata a una nuova pipeline del generatore di codice che integrava proto-plus per migliorare l'ergonomia dell'interfaccia dei messaggi protobuf facendo in modo che si comportino più come oggetti Python nativi. Lo svantaggio di questo miglioramento è che il proto-plus introduce un sovraccarico di prestazioni.

Prestazioni proto-plus

Uno dei vantaggi principali di Proto-plus è che converte i messaggi protobuf e i tipi ben noti in tipi Python nativi attraverso un processo chiamato marshalling dei tipi.

Il marshalling si verifica quando si accede a un campo su un'istanza di messaggio proto-plus, in particolare quando un campo viene letto o impostato, ad esempio, in una definizione protobuf:

syntax = "proto3";

message Dog {
  string name = 1;
}

Quando questa definizione viene convertita in una classe proto-plus, avrà il seguente aspetto:

import proto

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

Puoi quindi inizializzare la classe Dog e accedere al relativo campo name come faresti con qualsiasi altro oggetto Python:

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

Durante la lettura e l'impostazione del campo name, il valore viene convertito da un tipo Python str nativo a un tipo string in modo che il valore sia compatibile con il runtime protobuf.

Nell'analisi che abbiamo condotto dal rilascio della versione 10.0.0, abbiamo stabilito che il tempo dedicato a queste conversioni di tipo ha un impatto abbastanza significativo sulle prestazioni da rendere importante agli utenti la possibilità di utilizzare i messaggi protobuf.

Casi d'uso per messaggi proto-plus e protobuf

Casi d'uso dei messaggi proto-plus

Proto-plus offre una serie di miglioramenti ergonomici rispetto ai messaggi protobuf, quindi è ideale per scrivere codice gestibile e leggibile. Essendo espongono oggetti Python nativi, sono più facili da usare e da capire.

Casi d'uso dei messaggi Protobuf

Utilizza i protobuf per casi d'uso sensibili alle prestazioni, in particolare nelle app che devono elaborare rapidamente report di grandi dimensioni o che creano richieste di modifica con un numero elevato di operazioni, ad esempio con BatchJobService o OfflineUserDataJobService.

Modifica dinamica dei tipi di messaggi

Dopo aver selezionato il tipo di messaggio appropriato per la tua app, potresti scoprire che devi utilizzare l'altro tipo per un flusso di lavoro specifico. In questo caso, è facile passare da un tipo all'altro in modo dinamico utilizzando le utilità offerte dalla libreria client. Utilizzare la stessa classe di messaggi Dog di cui sopra:

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)

Differenze nell'interfaccia dei messaggi Protobuf

L'interfaccia proto+ è documentata in dettaglio, ma qui metteremo in evidenza alcune differenze chiave che riguardano i casi d'uso comuni per la libreria client di Google Ads.

Serializzazione in byte

Messaggi protocollo più

serialized = type(campaign).serialize(campaign)
deserialized = type(campaign).deserialize(serialized)

Messaggi Protobuf

serialized = campaign.SerializeToString()
deserialized = campaign.FromString(serialized)

Serializzazione JSON

Messaggi protocollo più

serialized = type(campaign).to_json(campaign)
deserialized = type(campaign).from_json(serialized)

Messaggi Protobuf

from google.protobuf.json_format import MessageToJson, Parse

serialized = MessageToJson(campaign)
deserialized = Parse(serialized, campaign)

Maschere dei campi

Il metodo helper per la maschera di campo fornito da api-core è progettato per utilizzare istanze di messaggio protobuf. Pertanto, quando utilizzi messaggi proto-plus, convertili in messaggi protobuf per utilizzare l'helper:

Messaggi protocollo più

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)

Messaggi Protobuf

from google.api_core.protobuf_helpers import field_mask

campaign = client.get_type("Campaign")
mask = field_mask(None, campaign)

Enum

Le enum esposte dai messaggi protocollo più sono istanze del tipo enum nativo di Python e quindi ereditano una serie di metodi di convenienza.

Recupero tipo enum

Quando utilizzi il metodo GoogleAdsClient.get_type per recuperare le enumerazioni, i messaggi restituiti sono leggermente diversi a seconda che utilizzi messaggi proto-plus o protobuf. Ad esempio:

Messaggi protocollo più

val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED

Messaggi Protobuf

val = client.get_type("CampaignStatusEnum").PAUSED

Per semplificare il recupero delle enum, è disponibile un attributo di convenienza nelle istanze GoogleAdsClient che ha un'interfaccia coerente, indipendentemente dal tipo di messaggio che stai utilizzando:

val = client.enums.CampaignStatusEnum.PAUSED

Recupero valore enum

A volte è utile conoscere il valore o l'ID campo di una determinata enumerazione. Ad esempio, PAUSED su CampaignStatusEnum corrisponde a 3:

Messaggi protocollo più

campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the value of campaign status
print(campaign.status.value)

Messaggi 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))

Recupero nome enum

A volte è utile conoscere il nome di un campo enum. Ad esempio, quando leggi oggetti dall'API, potresti voler sapere a quale stato della campagna corrisponde l'int 3:

Messaggi protocollo più

campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the name of campaign status
print(campaign.status.name)

Messaggi 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)

Campi ripetuti

Come descritto nei documenti proto-plus, i campi ripetuti sono generalmente equivalenti agli elenchi digitati, il che significa che si comportano in modo quasi identico a un list.

Aggiunta ai campi scalari ripetuti

Quando aggiungi valori ai campi scalar type ripetuti, ad esempio i campi string o int64, l'interfaccia è la stessa indipendentemente dal tipo di messaggio:

Messaggi protocollo più

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

Messaggi Protobuf

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

Sono inclusi anche tutti gli altri metodi list comuni, ad esempio extend:

Messaggi protocollo più

ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])

Messaggi Protobuf

ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])

Aggiunta di tipi di messaggi ai campi ripetuti

Se il campo ripetuto non è di tipo scalare, il comportamento quando li aggiungi a campi ripetuti è leggermente diverso:

Messaggi protocollo più

frequency_cap = client.get_type("FrequencyCapEntry")
frequency_cap.cap = 100
campaign.frequency_caps.append(frequency_cap)

Messaggi Protobuf

# The add method initializes a message and adds it to the repeated field
frequency_cap = campaign.frequency_caps.add()
frequency_cap.cap = 100

Assegnare campi ripetuti

Per i campi ripetuti sia scalari che non scalabili, puoi assegnare elenchi al campo in diversi modi:

Messaggi protocollo più

# In proto-plus it's possible to use assignment.
urls = ["https://www.example.com"]
ad.final_urls = urls

Messaggi 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

Messaggi vuoti

A volte è utile sapere se un'istanza di un messaggio contiene informazioni o se ha dei suoi campi impostati.

Messaggi protocollo più

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

Messaggi Protobuf

is_empty = campaign.ByteSize() == 0

Copia del messaggio

Per i messaggi proto-plus e protobuf, consigliamo di utilizzare il metodo helper copy_from in GoogleAdsClient:

client.copy_from(campaign, other_campaign)

Campi del messaggio vuoti

La procedura per impostare i campi dei messaggi vuoti è la stessa, indipendentemente dal tipo di messaggio utilizzato. Devi solo copiare un messaggio vuoto nel campo in questione. Consulta la sezione Copia del messaggio e la guida Campi messaggio vuoti. Ecco un esempio di come impostare un campo di messaggio vuoto:

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

Nomi dei campi che sono parole riservate

Quando utilizzi messaggi proto-plus, i nomi dei campi vengono visualizzati automaticamente con un trattino basso finale se il nome è anche una parola riservata in Python. Ecco un esempio di utilizzo di un'istanza Asset:

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

L'elenco completo dei nomi riservati viene creato nel modulo gapic generatore. Puoi anche accedervi in modo programmatico.

Innanzitutto, installa il modulo:

python -m pip install gapic-generator

Quindi, in un REPL o uno script Python:

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

Nota: l'aumento dei campi i cui nomi sono parole riservate non influisce sulle query GAQL. Pertanto, se richiedi il campo Asset.type in una richiesta Search o SearchStream, non includere un trattino basso finale nella stringa di query.

Presenza sul campo

Poiché i campi delle istanze di messaggio protobuf hanno valori predefiniti, non è sempre intuitivo sapere se un campo è stato impostato o meno.

Messaggi protocollo più

# Use the "in" operator.
has_field = "name" in campaign

Messaggi Protobuf

campaign = client.get_type("Campaign")
# Determines whether "name" is set and not just an empty string.
campaign.HasField("name")

L'interfaccia della classe protobuf Message ha un metodo HasField che determina se il campo di un messaggio è stato impostato, anche se è stato impostato su un valore predefinito.

Metodi dei messaggi Protobuf

L'interfaccia dei messaggi protobuf include alcuni metodi pratici che non fanno parte dell'interfaccia proto-plus. Tuttavia, è semplice accedervi convertendo un messaggio proto-plus nella sua controparte 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())

Issue Tracker

In caso di domande su queste modifiche o di problemi durante la migrazione alla versione 14.0.0 della libreria, segnala un problema sul nostro tracker.