Cómo trabajar con tipos de protobuf

Dado que la API de Google Ads usa proto3 como su formato de carga útil predeterminado, es importante comprender algunas convenciones y tipos de búferes de protocolo cuando trabajas con la biblioteca cliente de .NET.

Campos opcionales

Muchos campos de la API de Google Ads están marcados como optional. Esto te permite distinguir entre los casos en los que el campo tiene un valor vacío y aquellos en los que el servidor no devuelve un valor para el campo. Estos campos se comportan como propiedades normales, excepto que también proporcionan métodos adicionales para borrar el campo y verificar si está configurado.

Por ejemplo, el campo Name del objeto Campaign está marcado como optional, por lo que puedes usar los siguientes métodos para trabajar con este campo:

// Get the name.
string name = campaign.Name;

// Set the name.
campaign.Name = name;

// Check if the campaign object has the name field set.
bool hasName = campaign.HasName();

// Clear the name field. Use this method to exclude the Name field from
// being sent to the server in a subsequent API call.
campaign.ClearName();

// Set the campaign name to an empty string value. This value will be
// sent to the server if you use this object in a subsequent API call.
campaign.Name = "";

// This throws a runtime ArgumentNullException. Use ClearName() instead.
campaign.Name = null;

Campos repetidos

Un array de campos se representa en la API de Google Ads como un RepeatedField de solo lectura.

Por ejemplo, el campo url_custom_parameters de una campaña es un campo repetido, por lo que se representa como un RepeatedField<CustomParameter> de solo lectura en la biblioteca cliente de .NET. RepeatedField<T> implementa la interfaz IList<T>.

Existen dos maneras de propagar una propiedad RepeatedField:

Método AddRange

Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
};

// Add values to UrlCustomParameters using the AddRange method.
campaign.UrlCustomParameters.AddRange(new CustomParameter[]
{
    new CustomParameter { Key = "season", Value = "christmas" },
    new CustomParameter { Key = "promocode", Value = "NY123" }
});

Sintaxis del inicializador de colecciones

// Option 1: Initialize the field directly.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    // Directly initialize the field.
    UrlCustomParameters =
    {
        new CustomParameter { Key = "season", Value = "christmas" },
        new CustomParameter { Key = "promocode", Value = "NY123" }
    }
};

// Option 2: Initialize using an intermediate variable.
CustomParameter[] parameters = new CustomParameter[]
{
    new CustomParameter { Key = "season", Value = "christmas" },
    new CustomParameter { Key = "promocode", Value = "NY123" }
};

Campaign campaign1 = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    // Initialize from an existing array.
    UrlCustomParameters = { parameters }
};

Campos Oneof

Algunos campos de la API de Google Ads se marcan como campos oneof, lo que significa que el campo puede contener diferentes tipos, pero solo un valor en un momento determinado. Los campos oneof son similares a un tipo de unión en el lenguaje de programación C.

La biblioteca de .NET implementa los campos oneof proporcionando una propiedad para cada tipo de valor que se puede almacenar en un campo oneof, con todas las propiedades que actualizan un campo de almacenamiento subyacente compartido.

Por ejemplo, el campo campaign_bidding_strategy de la campaña se marca como un campo oneof. Esta clase se implementa de la siguiente manera (el código se simplificó para mayor brevedad):

public sealed partial class Campaign : pb::IMessage<Campaign>
{
    object campaignBiddingStrategy_ = null;
    CampaignBiddingStrategyOneofCase campaignBiddingStrategyCase_;

    public ManualCpc ManualCpc
    {
        get
        {
            return campaignBiddingStrategyCase_ ==
                CampaignBiddingStrategyOneofCase.ManualCpc
                ? (ManualCpc)campaignBiddingStrategy_ : null;
        }
        set
        {
            campaignBiddingStrategy_ = value;
            campaignBiddingStrategyCase_ =
                CampaignBiddingStrategyOneofCase.ManualCpc;
        }
    }

    public ManualCpm ManualCpm
    {
        get
        {
            return campaignBiddingStrategyCase_ ==
                CampaignBiddingStrategyOneofCase.ManualCpm
                ? (ManualCpm)campaignBiddingStrategy_ : null;
        }
        set
        {
            campaignBiddingStrategy_ = value;
            campaignBiddingStrategyCase_ =
                CampaignBiddingStrategyOneofCase.ManualCpm;
        }
    }

    public CampaignBiddingStrategyOneofCase CampaignBiddingStrategyCase
    {
        get { return campaignBiddingStrategyCase_; }
    }
}

Como las propiedades de oneof comparten el almacenamiento, una asignación puede reemplazar una anterior, lo que genera errores sutiles. Por ejemplo:

Campaign campaign = new Campaign()
{
    ManualCpc = new ManualCpc(),
    ManualCpm = new ManualCpm()
};

En este caso, campaign.ManualCpc es null porque inicializar la propiedad campaign.ManualCpm reemplaza la inicialización anterior de campaign.ManualCpc.

Conversión a otros formatos

Convierte al formato JSON

Puedes convertir objetos protobuf al formato JSON y viceversa con Google.Protobuf.JsonFormatter. Esto es útil cuando se compilan sistemas que necesitan interactuar con otros sistemas que requieren formatos basados en texto, como JSON o XML.

using Google.Protobuf;

GoogleAdsRow row = new GoogleAdsRow()
{
    Campaign = new Campaign()
    {
        Id = 123,
        Name = "Campaign 1",
        ResourceName = ResourceNames.Campaign(1234567890, 123)
    }
};

// Serialize to JSON and back.
string json = JsonFormatter.Default.Format(row);
row = GoogleAdsRow.Parser.ParseJson(json);

Convertir a bytes

Puedes serializar un objeto en bytes y viceversa con Google.Protobuf. La serialización binaria es más eficiente en términos de memoria y almacenamiento que el formato JSON.

using Google.Protobuf;

GoogleAdsRow row = new GoogleAdsRow()
{
    Campaign = new Campaign()
    {
        Id = 123,
        Name = "Campaign 1",
        ResourceName = ResourceNames.Campaign(1234567890, 123)
    }
};

// Serialize to bytes and back.
byte[] bytes = row.ToByteArray();
row = GoogleAdsRow.Parser.ParseFrom(bytes);