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ştir. Bu, alanın boş bir değere sahip olduğu durumları, sunucunun alan için bir değer geri göndermediği durumları 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ştir.
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 temsil edilir.
Örneğin, bir kampanyanın url_custom_parameters alanı yinelenen bir alan olduğundan .NET istemci kitaplığında salt okunur RepeatedField<CustomParameter> olarak temsil edilir.
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ğ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" }
});
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 alanı olarak işaretlenmiştir. Bu, alanın farklı türlerde ancak belirli bir zamanda yalnızca bir değer tutabileceği anlamına gelir. OneOf alanları, C'deki union türüne benzer.
.NET kitaplığı, OneOf alanında tutulabilecek her değer türü için bir özellik ve paylaşılan bir sınıf alanını güncelleyen tüm özellikler sağlayarak OneOf alanlarını uygular.
Örneğin, kampanyanın campaign_bidding_strategy alanı OneOf alanı olarak işaretlenmiştir. Bu sınıf aşağıdaki şekilde uygulanır (kod kısalık 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ığı için bir ödev, önceki bir ödevin üzerine yazabilir ve bu da gözden kaçan hatalara neden olabilir. Örneğin,
Campaign campaign = new Campaign()
{
ManualCpc = new ManualCpc()
{
EnhancedCpcEnabled = true
},
ManualCpm = new ManualCpm()
{
}
};
Bu durumda, campaign.ManualCpm alanının başlatılması campaign.ManualCpc için önceki başlatmanın üzerine yazacağından campaign.ManualCpc artık null değerine sahiptir.
Diğer biçimlere dönüştürme
Protobuf nesnelerini JSON biçimine ve tersine 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);
Bir nesneyi baytlara seri hale getirip geri dönüştürebilirsiniz. İkili serileştirme, JSON biçiminden 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);