Protobuf türleriyle çalışma

Google Ads API, varsayılan yük biçimi olarak proto3 kullandığından .NET istemci kitaplığıyla çalışırken birkaç Protokol Arabelleği kuralını ve türünü anlamak önemlidir.

İsteğe bağlı alanlar

Google Ads API'deki birçok alan optional olarak işaretlenir. Bu sayede, alanın boş bir değere sahip olduğu durumlar ile sunucunun alan için bir değer döndürmediği durumlar arasında ayrım yapabilirsiniz. Bu alanlar, normal özellikler gibi davranır. Ancak alanı temizlemek ve alanın ayarlanıp ayarlanmadığını kontrol etmek için ek yöntemler de sunar.

Örneğin, Campaign nesnesinin Name alanı optional olarak işaretlenir. Bu nedenle, bu alanla çalışmak için aşağıdaki yöntemleri kullanabilirsiniz:

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

Yinelenen alanlar

Alan dizisi, Google Ads API'de salt okunur bir RepeatedField olarak temsil edilir.

Örneğin, bir kampanyanın url_custom_parameters alanı tekrarlanan bir alandır. Bu nedenle, .NET istemci kitaplığında salt okunur RepeatedField<CustomParameter> olarak gösterilir. RepeatedField<T>, IList<T> arayüzünü uygular.

RepeatedField özelliğini iki şekilde doldurabilirsiniz:

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

Oneof alanları

Google Ads API'deki bazı alanlar oneof alanları olarak işaretlenir. Bu, alanın farklı türler içerebileceği ancak belirli bir zamanda yalnızca tek bir değer tutabileceği anlamına gelir. oneof alanları, C programlama dilindeki birleşim türüne benzer.

.NET kitaplığı, oneof alanlarını, oneof alanında tutulabilecek her değer türü için bir özellik sağlayarak uygular. Tüm özellikler, paylaşılan bir temel depolama alanını günceller.

Örneğin, kampanyanın campaign_bidding_strategy alanı oneof alanı olarak işaretlenir. Bu sınıf aşağıdaki gibi uygulanır (kod, kısa olması için basitleştirilmiştir):

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

oneof özellikleri depolama alanını paylaştığından bir atama, önceki bir atamanın üzerine yazarak fark edilmesi zor hatalara neden olabilir. Örneğin:

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

Bu durumda, campaign.ManualCpm özelliğinin başlatılması campaign.ManualCpc için önceki başlatma işleminin üzerine yazıldığından campaign.ManualCpc, null olur.

Diğer biçimlere dönüştürme

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