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

Google Ads API, varsayılan yük biçimi olarak Protobuf'u 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;

Tekrarlanan türler

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.

Daha eski C# sürümü: AddRange yöntemini kullanarak değer ekleme

Aşağıda bir örnek verilmiştir.

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

Daha yeni C# sürümleri: Koleksiyon başlatıcı söz dizimini kullanma

// 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 türleri

Google Ads API'deki bazı alanlar OneOf 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'deki birleşim türüne benzer.

.NET kitaplığı, OneOf alanları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 özellikleri 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ı null olur. Bunun nedeni, campaign.ManualCpm alanının başlatılmasının campaign.ManualCpc için önceki başlatma işleminin üzerine yazmasıdır.

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

Protobuf nesnelerini kolayca 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);

Ayrıca bir nesneyi baytlara ve tekrar nesneye de seri hale getirebilirsiniz. İ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);