Con el parámetro de configuración use_proto_plus, puedes especificar si deseas que la biblioteca devuelva mensajes proto-plus o mensajes de protobuf. Para obtener detalles sobre cómo establecer este parámetro, consulta la documentación de configuración.
En esta sección, se describen las implicaciones en el rendimiento de cada opción para que puedas elegir el mejor enfoque para tu aplicación.
Comparación entre los mensajes de Proto-plus y 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 hace que se comporten más como objetos estándar de Python. Sin embargo, esto significa que usar proto-plus introduce una sobrecarga de rendimiento.
Rendimiento de Proto-plus
Uno de los principales beneficios de proto-plus es que convierte los mensajes de protobuf y los tipos conocidos en tipos integrados de Python a través de un proceso llamado serialización de tipos.
El proceso de serialización ocurre cuando se accede a un campo en una instancia de mensaje de 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 de 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 str integrado de Python a un tipo string para que el valor sea compatible con el tiempo de ejecución de Protobuf.
El tiempo que se dedica a realizar estas conversiones de tipo tiene un impacto en el rendimiento lo suficientemente grande como para que decidas, según las necesidades de tu aplicación, si usar mensajes de proto-plus o de protobuf.
Casos de uso de mensajes de 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 de protobuf, por lo que son ideales para escribir código legible y fácil de mantener. Como exponen objetos estándar de Python, son más fáciles de usar y comprender.
- 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 rápidamente o que compilan solicitudes de mutación con una gran cantidad de operaciones, por ejemplo, con
BatchJobServiceoOfflineUserDataJobService.
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, puedes cambiar entre los dos tipos de forma dinámica con las utilidades que ofrece la biblioteca cliente. Con la misma clase de mensaje Dog de antes, haz lo siguiente:
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 está documentada en detalle, y las siguientes secciones destacan las diferencias clave que afectan los casos de uso comunes de la biblioteca cliente de Google Ads.
Serialización de bytes
- Mensajes de 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 auxiliar de máscara de campo que proporciona api-core está diseñado para usar instancias de mensajes de protobuf. Cuando uses mensajes de proto-plus, conviértelos en mensajes de protobuf para usar el asistente:
- Mensajes de 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)
Enums
Los enums expuestos por los mensajes de proto-plus son instancias del tipo enum integrado de Python y, por lo tanto, heredan varios métodos convenientes.
Recuperación del tipo de enumeración
Cuando se usa el método GoogleAdsClient.get_type para recuperar enumeraciones, los mensajes que se devuelven son ligeramente diferentes según si se usan mensajes de proto-plus o de 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, independientemente del tipo de mensaje que uses:
val = client.enums.CampaignStatusEnum.PAUSED
Recuperación de valores de enumeración
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 # 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"))
Recuperación del nombre de la enumeración
A veces, es útil conocer el nombre de un campo de enumeración. Por ejemplo, cuando lees objetos de la API, es posible que desees saber a qué estado de la campaña corresponde el número entero 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 print(status_enum.CampaignStatus.Name(campaign.status))
Campos repetidos
Como se describe en la documentación de proto-plus, los campos repetidos generalmente son equivalentes a las listas escritas, lo que significa que se comportan casi de forma idéntica a un list.
Agrega valores a campos escalares repetidos
Cuando agregas valores a campos de tipo escalar repetidos, por ejemplo, campos string o int64, la interfaz es la misma, independientemente del tipo de mensaje:
- Mensajes de 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 de list comunes, por ejemplo, extend:
- Mensajes de 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"] )
Agrega tipos de mensajes a campos repetidos
Si el campo repetido no es un tipo escalar, el comportamiento cuando se agregan 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
Asigna campos repetidos
En el caso de los campos repetidos escalares y no escalares, puedes asignar listas al campo de diferentes maneras:
- Mensajes de 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 alguno de sus campos está configurado.
- Mensajes de Proto-plus
# When using proto-plus messages you can check the message for truthiness. is_empty = not bool(campaign)
- Mensajes de Protobuf
is_empty = campaign.ByteSize() == 0
Copia del mensaje
Para los mensajes de proto-plus y Protobuf, usa 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 mensajes vacíos es el mismo, independientemente del tipo de mensaje que uses. Copias un mensaje vacío en el campo en cuestión. Consulta la sección Copia del mensaje y la guía Campos de mensajes vacíos. En el siguiente ejemplo, se muestra 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 de proto-plus, los nombres de los campos aparecen automáticamente con un guion bajo final si el nombre también es una palabra reservada en Python. En el siguiente ejemplo, se muestra 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 del generador de gapic. También se puede acceder a ella de forma programática.
Primero, instala el módulo:
python -m pip install gapic-generator
Luego, en un REPL o una secuencia de comandos de Python, haz lo siguiente:
import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)
Presencia de campos
Dado 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ó un submensaje, un campo oneof o un campo escalar optional en un mensaje, incluso si se configuró con un valor predeterminado.
(Llamar a HasField en campos escalares no opcionales en proto3 genera un ValueError).
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, puedes acceder a ellos convirtiendo un mensaje de proto-plus a su equivalente de 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()
Herramienta de seguimiento de errores
Si tienes alguna pregunta sobre estos cambios o algún problema para migrar a la versión más reciente de la biblioteca, crea un problema en el Issue Tracker.