Protokol Arabelleği Türleriyle Çalışma

Google Ads API, varsayılan yük biçimi olarak proto3'ü kullandığından API ile çalışırken birkaç protobuf 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 durumlarla sunucunun alan için bir değer geri göndermediği durumları ayırt edebilirsiniz. Bu alanlar, alanı temizlemek ve alanın ayarlanıp ayarlanmadığını kontrol etmek için ek yöntemler de sunmaları dışında normal alanlar gibi davranır.

Örneğin, Campaign nesnesinin Name alanı isteğe bağlı 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 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;

Yinelenen alanlar

Alan dizisi, Google Ads API'de salt okunur RepeatedField olarak gösterilir.

Ö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, IList<T> arayüzünü uygular.

RepeatedField alanını doldurmanın iki yolu vardır.

AddRange yöntemi

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

Koleksiyon başlatıcı söz dizimi

// 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 alanında tutulabilecek her değer türü için bir özellik sağlayarak oneof alanlarını uygular ve tüm özellikler paylaşılan bir sınıf 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 (kısa olması için kod 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 mülkleri depolama alanını paylaştığından bir atama, önceki bir atamanın üzerine yazabilir ve bu da küçük hatalara yol açabilir. Örneğin,

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

    }
};

Bu durumda, campaign.ManualCpc alanının başlatılması campaign.ManualCpm alanının önceki başlatma işleminin üzerine yazacağından campaign.ManualCpc artık null olur.

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

JSON biçimine dönüştürme

Protobuf nesnelerini JSON biçimine ve tersine dönüştürebilirsiniz. Bu, JSON veya XML gibi metin tabanlı biçimlerde veri gerektiren diğer sistemlerle arayüz oluşturması gereken sistemler geliştirirken faydalıdır.

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

Bayta dönüştürme

Bir nesneyi baytlara ve tekrar nesneye serileştirebilirsiniz. İkili serileştirme, JSON biçimine göre daha az bellek ve depolama alanı kullanır.

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