Mensajes de protobuf

Con el parámetro de configuración use_proto_plus, puedes especificar si quieres que la biblioteca muestre mensajes proto-plus o mensajes protobuf. Para obtener detalles sobre cómo configurar este parámetro, consulta los documentos de configuración.

En esta sección, se describen las implicaciones de rendimiento que tiene elegir qué tipos de mensajes usar; por lo tanto, te recomendamos que leas y comprendas las opciones para tomar una decisión fundamentada.

Comparación entre proto-plus y mensajes protobuf

La canalización del generador de código integra proto-plus como una forma de mejorar la ergonomía de la interfaz de mensajes de protobuf, ya que los hace comportarse más como objetos nativos de Python. Sin embargo, esto significa que el uso de proto-plus presenta una sobrecarga de rendimiento.

Rendimiento de proto-plus

Uno de los beneficios principales de proto-plus es que convierte los mensajes de protobuf y los tipos conocidos en tipos nativos de Python a través de un proceso llamado agrupación de tipos.

La vinculación se produce cuando se accede a un campo en una instancia de mensaje proto-plus, específicamente cuando se lee o se establece un campo, por ejemplo, en una definición de protobuf:

syntax = "proto3";

message Dog {
  string name = 1;
}

Cuando esta definición se convierte en una clase proto-plus, se ve de la siguiente manera:

import proto

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

Luego, puedes inicializar la clase Dog y acceder a su campo name como lo harías con cualquier otro objeto de Python:

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

Cuando se lee y se configura el campo name, el valor se convierte de un tipo nativo str de Python a un tipo string para que el valor sea compatible con el entorno de ejecución de protobuf.

En función de nuestros análisis de rendimiento, determinamos que el tiempo dedicado a realizar este tipo de conversiones tiene un impacto en el rendimiento lo suficientemente grande como para que los usuarios decidan, según sus necesidades, si usar o no mensajes de protobuf.

Casos de uso para mensajes proto-plus y protobuf

Casos de uso de mensajes de proto-plus
Proto-plus ofrece varias mejoras ergonómicas en comparación con los mensajes protobuf, por lo que son ideales para escribir código legible y sostenible. Dado que exponen objetos nativos de Python, son más fáciles de usar y entender.
Casos de uso de mensajes de protobuf
Usa protobufs para casos de uso sensibles al rendimiento, específicamente en apps que necesitan procesar informes grandes con rapidez o que compilan solicitudes de mutación con una gran cantidad de operaciones, por ejemplo, con BatchJobService o OfflineUserDataJobService.

Cómo cambiar los tipos de mensajes de forma dinámica

Después de seleccionar el tipo de mensaje adecuado para tu app, es posible que necesites usar el otro tipo para un flujo de trabajo específico. En este caso, es fácil cambiar entre los dos tipos de forma dinámica con las utilidades que ofrece la biblioteca cliente. Con la misma clase de mensaje Dog anterior:

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)

Diferencias en la interfaz de mensajes de Protobuf

La interfaz de proto-plus se documenta en detalle, pero aquí destacaremos algunas diferencias clave que afectan los casos de uso comunes de la biblioteca cliente de Google Ads.

Serialización de bytes

Mensajes proto-plus
serialized = type(campaign).serialize(campaign)
deserialized = type(campaign).deserialize(serialized)
Mensajes de Protobuf
serialized = campaign.SerializeToString()
deserialized = campaign.FromString(serialized)

Serialización de JSON

Mensajes de proto-plus
serialized = type(campaign).to_json(campaign)
deserialized = type(campaign).from_json(serialized)
Mensajes de protobuf
from google.protobuf.json_format import MessageToJson, Parse

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

Máscaras de campo

El método de ayuda de máscara de campo que proporciona api-core está diseñado para usar instancias de mensajes de protobuf. Por lo tanto, cuando uses mensajes proto-plus, conviértelos en mensajes protobuf para usar el asistente:

Mensajes 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)
Mensajes de protobuf
from google.api_core.protobuf_helpers import field_mask

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

Enumeraciones

Las enumeraciones que exponen los mensajes proto-plus son instancias del tipo enum nativo de Python y, por lo tanto, heredan varios métodos de conveniencia.

Recuperación de tipos de enum

Cuando usas el método GoogleAdsClient.get_type para recuperar enumeraciones, los mensajes que se muestran son un poco diferentes en función de si usas mensajes proto-plus o protobuf. Por ejemplo:

Mensajes de proto-plus
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
Mensajes de Protobuf
val = client.get_type("CampaignStatusEnum").PAUSED

Para simplificar la recuperación de enumeraciones, hay un atributo de conveniencia en las instancias de GoogleAdsClient que tiene una interfaz coherente, sin importar el tipo de mensaje que uses:

val = client.enums.CampaignStatusEnum.PAUSED

Recuperación de valores de enum

A veces, es útil conocer el valor, o el ID de campo, de una enumeración determinada. Por ejemplo, PAUSED en CampaignStatusEnum corresponde a 3:

Mensajes de proto-plus
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the value of campaign status
print(campaign.status.value)
Mensajes de 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))

Recuperación de nombres de enum

A veces, es útil conocer el nombre de un campo de enumeración. Por ejemplo, cuando lee objetos de la API, es posible que desees saber a qué estado de la campaña corresponde el int 3:

Mensajes de proto-plus
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the name of campaign status
print(campaign.status.name)
Mensajes de 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)

Campos repetidos

Como se describe en los documentos de proto-plus, los campos repetidos suelen ser equivalentes a listas escritas, lo que significa que se comportan de manera casi idéntica a un list.

Cómo agregar valores a campos escalares repetidos

Cuando agregas valores a campos repetidos de tipo escalar, por ejemplo, campos string o int64, la interfaz es la misma independientemente del tipo de mensaje:

Mensajes proto-plus
ad.final_urls.append("https://www.example.com")
Mensajes de Protobuf
ad.final_urls.append("https://www.example.com")

Esto también incluye todos los demás métodos comunes de list, por ejemplo, extend:

Mensajes proto-plus
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
Mensajes de protobuf
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])

Cómo agregar tipos de mensajes a campos repetidos

Si el campo repetido no es un tipo escalar, el comportamiento cuando se agrega a campos repetidos es ligeramente diferente:

Mensajes de proto-plus
frequency_cap = client.get_type("FrequencyCapEntry")
frequency_cap.cap = 100
campaign.frequency_caps.append(frequency_cap)
Mensajes de Protobuf
# The add method initializes a message and adds it to the repeated field
frequency_cap = campaign.frequency_caps.add()
frequency_cap.cap = 100

Asignar campos repetidos

En el caso de los campos repetidos escalares y no escalares, puedes asignar listas al campo de diferentes maneras:

Mensajes proto-plus
# In proto-plus it's possible to use assignment.
urls = ["https://www.example.com"]
ad.final_urls = urls
Mensajes de 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

Mensajes vacíos

A veces, es útil saber si una instancia de mensaje contiene información o si tiene alguno de sus campos configurados.

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

Texto del mensaje

Para los mensajes proto-plus y protobuf, te recomendamos que uses el método auxiliar copy_from en GoogleAdsClient:

client.copy_from(campaign, other_campaign)

Campos de mensaje vacíos

El proceso para configurar campos de mensaje vacíos es el mismo independientemente del tipo de mensaje que uses. Solo debes copiar un mensaje vacío en el campo en cuestión. Consulta la sección Texto del mensaje y la guía Campos de mensajes vacíos. Este es un ejemplo de cómo configurar un campo de mensaje vacío:

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

Nombres de campos que son palabras reservadas

Cuando se usan mensajes proto-plus, los nombres de campo aparecen automáticamente con una virgulilla al final si el nombre también es una palabra reservada en Python. A continuación, se muestra un ejemplo de cómo trabajar con una instancia de Asset:

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

La lista completa de nombres reservados se construye en el módulo gapic generator. También se puede acceder a él de forma programática.

Primero, instala el módulo:

python -m pip install gapic-generator

Luego, en una REPL o secuencia de comandos de Python, haz lo siguiente:

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

Presencia en el campo

Debido a que los campos de las instancias de mensajes de protobuf tienen valores predeterminados, no siempre es intuitivo saber si se configuró un campo o no.

Mensajes de proto-plus
# Use the "in" operator.
has_field = "name" in campaign
Mensajes de protobuf
campaign = client.get_type("Campaign")
# Determines whether "name" is set and not just an empty string.
campaign.HasField("name")

La interfaz de la clase Message de protobuf tiene un método HasField que determina si se configuró el campo en un mensaje, incluso si se configuró en un valor predeterminado.

Métodos de mensajes de protobuf

La interfaz de mensajes de protobuf incluye algunos métodos convenientes que no forman parte de la interfaz de proto-plus. Sin embargo, es fácil acceder a ellos convirtiendo un mensaje de proto-plus en su contraparte de 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())

Seguimiento de problemas

Si tienes alguna pregunta sobre estos cambios o algún problema para migrar a la versión más reciente de la biblioteca, informa el error en nuestra herramienta de seguimiento.