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 kurallarını ve türlerini anlamanız önemlidir.

İsteğe bağlı alanlar

Google Ads API'deki birçok alan optional olarak işaretlenmiştir. Bu, alanın boş bir değere sahip olduğu ve sunucunun alan için değer geri göndermediği durumları birbirinden ayırt etmenize olanak tanır. Bu alanlar normal alanlar gibi davranır ancak alanı temizlemek ve alanın ayarlanıp ayarlanmadığını kontrol etmek için ek yöntemler de sağlar.

Örneğin, Campaign nesnesinin Name alanı isteğe bağlı olarak işaretlenmiş. Dolayısıyla bu alanda ç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 temsil edilir.

Kampanyanın url_custom_parameters alanı yinelenen bir alan örnek olarak verilebilir. Bu nedenle .NET istemci kitaplığında salt okunur RepeatedField<CustomParameter> olarak temsil edilir.

RepeatedField, IList<T> arayüzünü uygular.

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

Eski C# sürümü: AddRange yöntemini kullanarak değerleri 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 }
};

Türlerden biri

Google Ads API'deki bazı alanlar OneOf alanları olarak işaretlenmiştir. Diğer bir deyişle, bu alan farklı türlerde ancak belirli bir zamanda yalnızca bir değer içerebilir. OneOf alanları, C'deki birlik türüne benzer.

.NET kitaplığı, OneOf alanında tutulabilecek her değer türü ve paylaşılan bir sınıf alanını güncelleyen tüm özellikler için bir özellik sağlayarak OneOf alanlarını uygular.

Örneğin, kampanyanın campaign_bidding_strategy alanı OneOf alanı olarak işaretlenir. Bu sınıf, aşağıdaki gibi uygulandı (kod kısaltılması 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 mülkleri depolama alanını paylaştığından, tek bir atama önceki bir atamanın üzerine yazılabilir. Bu durumda, küçük hatalar ortaya çıkabilir. Örneğin,

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

    }
};

Bu durumda, campaign.ManualCpc alanı campaign.ManualCpm alanı başlatıldığında campaign.ManualCpc için yapılan önceki başlatmanın üzerine yazılacağından artık null.

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

Protobuf nesnelerini JSON biçimine ve tersine kolayca dönüştürebilirsiniz. Bu yöntem, JSON veya XML gibi metin tabanlı biçimlerde veri gerektiren diğer sistemlerle arayüz yapması gereken sistemler oluştururken kullanışlı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 geriye dönük olarak serileştirebilirsiniz. İkili program serileştirme, JSON biçiminden daha fazla bellek ve depolama alanı sunar.

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