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şaretlenmiş. Bu sayede, alanın boş bir değere sahip olduğu durumları ile sunucunun alan için geri bir değer göndermediği durumları birbirinden ayırt edebilirsiniz. Bu alanlar, alanı temizlemek ve alanın ayarlanıp ayarlanmadığını kontrol etmek için ek yöntemler sağlaması dışında normal alanlar gibi davranır.

Örneğin, Campaign nesnesinin Name alanı isteğe bağlı olarak işaretlenmiştir. 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 gösterilir.

Bir kampanyanın url_custom_parameters alanı yinelenen bir alan olduğundan .NET istemci kitaplığında salt okunur RepeatedField<CustomParameter> olarak gösterilir.

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

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

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

// 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. Bu alan, farklı türlerde ancak aynı anda yalnızca bir değer içerebilir. Alanlardan biri C'deki birleştirme türüne benzer.

.NET kitaplığı, OneOf alanında bulunabilecek 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 değeri 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 yazabilir ve bu nedenle küçük hatalar ortaya çıkabilir. Örneğin,

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

    }
};

Bu durumda, campaign.ManualCpm alanı ilk kullanıma sunulduğunda campaign.ManualCpc için önceki başlatmanın üzerine yazıldığından campaign.ManualCpc artık null durumundadır.

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

Protobuf nesnelerini kolayca JSON biçimine ve tersinden kolayca dönüştürebilirsiniz. Bu, JSON veya XML gibi metin tabanlı biçimlerde veri gerektiren diğer sistemlerle arayüz oluşturması 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 dönüştürüp eski haline getirebilirsiniz. İkili program serileştirmesi, JSON biçiminden daha fazla bellek ve depolama alanı tasarrufu sağlar.

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