เนื่องจาก Google Ads API ใช้ Protobuf เป็นรูปแบบเพย์โหลดเริ่มต้น คุณจึงควรทำความเข้าใจรูปแบบและประเภท Protobuf บางอย่างเมื่อทํางานกับ API
ช่องที่ไม่บังคับ
ช่องหลายช่องใน Google Ads API มีการทำเครื่องหมายเป็น optional
ซึ่งจะช่วยให้คุณแยกแยะระหว่างกรณีที่ช่องมีค่าว่าง กับกรณีที่เซิร์ฟเวอร์ไม่ได้ส่งค่าสําหรับช่องกลับ ช่องเหล่านี้ทํางานเหมือนช่องทั่วไป ยกเว้นว่ายังมีวิธีการเพิ่มเติมในการล้างช่องและตรวจสอบว่ามีการกําหนดค่าช่องหรือไม่
เช่น ช่อง Name
ของออบเจ็กต์ Campaign
มีการทำเครื่องหมายว่าไม่บังคับ
คุณจึงใช้วิธีการต่อไปนี้กับฟิลด์นี้ได้
// 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;
ประเภทที่ซ้ำ
อาร์เรย์ฟิลด์จะแสดงใน Google Ads API เป็น readonly
RepeatedField
ตัวอย่างเช่น ช่อง url_custom_parameters
ของแคมเปญเป็นช่องที่ซ้ำกัน จึงแสดงเป็น RepeatedField<CustomParameter>
แบบอ่านอย่างเดียวในไลบรารีไคลเอ็นต์ .NET
RepeatedField
ใช้IList<T>
อินเทอร์เฟซ
การป้อนข้อมูลในช่อง RepeatedField
ทําได้ 2 วิธี
C# เวอร์ชันเก่า: เพิ่มค่าโดยใช้เมธอด AddRange
โปรดดูตัวอย่างด้านล่าง
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" }
});
C# เวอร์ชันใหม่กว่า: ใช้ไวยากรณ์ตัวเริ่มต้นคอลเล็กชัน
// 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
ช่องบางช่องใน Google Ads API มีการทำเครื่องหมายเป็นช่อง OneOf
ซึ่งหมายความว่าช่องดังกล่าวสามารถเก็บค่าประเภทต่างๆ ได้ แต่มีเพียงค่าเดียวในแต่ละครั้ง ฟิลด์ OneOf จะคล้ายกับประเภทยูเนียนใน C
ไลบรารี .NET ใช้ฟิลด์ OneOf โดยระบุพร็อพเพอร์ตี้ 1 รายการสำหรับค่าแต่ละประเภทที่เก็บไว้ในฟิลด์ OneOf และพร็อพเพอร์ตี้ทั้งหมดจะอัปเดตฟิลด์คลาสที่แชร์
เช่น campaign_bidding_strategy
ของแคมเปญมีการทำเครื่องหมายเป็นช่อง OneOf
คลาสนี้ใช้งานได้ดังนี้ (โค้ดที่เขียนให้เข้าใจง่าย)
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 ใช้พื้นที่เก็บข้อมูลร่วมกัน งานหนึ่งจึงเขียนทับงานก่อนหน้าได้ ซึ่งอาจทำให้เกิดข้อบกพร่องเล็กๆ น้อยๆ ตัวอย่างเช่น
Campaign campaign = new Campaign()
{
ManualCpc = new ManualCpc()
{
EnhancedCpcEnabled = true
},
ManualCpm = new ManualCpm()
{
}
};
ในกรณีนี้ campaign.ManualCpc
จะกลายเป็น null
เนื่องจากการเริ่มต้นค่าช่อง campaign.ManualCpm
จะเขียนทับการเริ่มต้นค่าก่อนหน้าสําหรับ campaign.ManualCpc
การแปลงเป็นรูปแบบอื่นๆ
คุณสามารถแปลงออบเจ็กต์ protobuf เป็นรูปแบบ JSON และในทางกลับกันได้ง่ายๆ ซึ่งจะมีประโยชน์เมื่อสร้างระบบที่ต้องเชื่อมต่อกับระบบอื่นๆ ที่ต้องการข้อมูลในรูปแบบข้อความ เช่น JSON หรือ XML
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);
นอกจากนี้ คุณยังจัดรูปแบบออบเจ็กต์เป็นไบต์และกลับเป็นออบเจ็กต์ได้อีกด้วย การจัดรูปแบบไบนารีใช้หน่วยความจําและพื้นที่เก็บข้อมูลได้มีประสิทธิภาพมากกว่ารูปแบบ JSON
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);