Cómo trabajar con tipos de protobuf

Dado que la API de Google Ads usa proto3 como formato de carga útil predeterminado, es importante comprender algunas convenciones y tipos de Protocol Buffers cuando se trabaja 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

En la API de Google Ads, un array de campos se representa 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 completar una propiedad RepeatedField:

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" }
});

// 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 están marcados como campos oneof, lo que significa que el campo puede contener diferentes tipos, pero solo un valor a la vez. Los campos oneof son similares a un tipo de unión en el lenguaje de programación C.

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

Por ejemplo, el campaign_bidding_strategy de la campaña se marca como un campo oneof. Esta clase se implementa de la siguiente manera (código simplificado 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_; }
    }
}

Dado que las propiedades de oneof comparten almacenamiento, una asignación puede reemplazar una asignación 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 la inicialización de la propiedad campaign.ManualCpm anula la inicialización anterior de campaign.ManualCpc.

Conversión a otros formatos

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

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