Utilizzare i tipi Protobuf

Poiché l'API Google Ads utilizza Protobuf come formato di payload predefinito, è importante per comprendere alcune convenzioni e tipi di Protobuf quando si lavora con l'API.

Campi facoltativi

Molti campi dell'API Google Ads sono contrassegnati come optional. Questo consente di distinguere i casi in cui il campo ha un valore vuoto rispetto al server non ha restituito un valore per il campo. Questi campi si comportano come normali campi, ma forniscono anche metodi aggiuntivi per svuotare il campo e verifica se il campo è impostato.

Ad esempio, il campo Name dell'oggetto Campaign è contrassegnato come facoltativo. Pertanto, puoi utilizzare i seguenti metodi per lavorare con questo 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 Name field from
// being sent to the server in a subsequent API call.
campaign.ClearName();

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

// This will throw a runtime error. Use ClearName() instead.
campaign.Name = null;

Tipi ripetuti

Un array di campi è rappresentato nell'API Google Ads in formato di sola lettura RepeatedField

Ad esempio, il campo url_custom_parameters di una campagna è un campo ripetuto. quindi è rappresentato come un RepeatedField<CustomParameter> di sola lettura in libreria client.

L'RepeatedField implementa i parametri IList<T> a riga di comando.

Esistono due modi per compilare un campo RepeatedField.

Versione C# precedente: aggiungi valori utilizzando il metodo AddRange

Di seguito è riportato un esempio.

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

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

Versioni C# più recenti: usa la sintassi di inizializzazione delle raccolte

// 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 }
};

Tipi OneOf

Alcuni campi nell'API Google Ads sono contrassegnati come campi OneOf, il che significa che il campo può contenere tipi diversi, ma un solo valore alla volta. Uno dei campi è simile al tipo di unione in C.

La libreria .NET implementa i campi OneOf fornendo una proprietà per ogni tipo di un valore che può essere contenuto in un campo OneOf e tutte le proprietà che aggiornano campo del corso condiviso.

Ad esempio, il valore campaign_bidding_strategy della campagna è contrassegnato come OneOf . Questa classe viene implementata come segue (codice semplificato per brevità):

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_; }
    }
}

Poiché le proprietà OneOf condividono lo spazio di archiviazione, un'assegnazione può sovrascrivere una precedente compito, causando sottili bug. Ad esempio,

Campaign campaign = new Campaign()
{
    ManualCpc = new ManualCpc()
    {
        EnhancedCpcEnabled = true
    },
    ManualCpm = new ManualCpm()
    {

    }
};

In questo caso, campaign.ManualCpc è ora null dall'inizializzazione della Il campo campaign.ManualCpm sovrascrive la precedente inizializzazione per campaign.ManualCpc.

Conversione in altri formati

Puoi convertire facilmente gli oggetti protobuf in formato JSON e viceversa. Questo è è utile quando si creano sistemi che devono interfacciarsi con altri sistemi richiedono dati in formati di testo come JSON o XML.

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

Puoi anche serializzare un oggetto in byte e viceversa. La serializzazione binaria è efficiente in termini di memoria e spazio di archiviazione rispetto al formato JSON.

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