Vì API Google Ads sử dụng Protobuf làm định dạng tải trọng mặc định, nên điều quan trọng là để tìm hiểu một số loại và quy ước Protobuf khi làm việc với API.
Trường tùy chọn (trường không bắt buộc)
Nhiều trường trong API Google Ads được đánh dấu là optional. Điều này cho phép bạn
phân biệt các trường hợp trường có giá trị trống so với máy chủ
đã không gửi lại giá trị cho trường. Các trường này hoạt động giống như thông thường
ngoại trừ các trường đó cũng cung cấp các phương pháp bổ sung để xoá trường đó và
kiểm tra xem trường này đã được thiết lập chưa.
Ví dụ: trường Name của đối tượng Campaign được đánh dấu là không bắt buộc.
Vì vậy, bạn có thể sử dụng các phương thức sau để làm việc với trường này.
// 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;
Loại lặp lại
Một mảng trường được biểu thị trong API Google Ads ở dạng chỉ đọc
RepeatedField.
Ví dụ: trường url_custom_parameters của chiến dịch là trường lặp lại,
nên nó được biểu thị dưới dạng RepeatedField<CustomParameter> chỉ đọc trong .NET
thư viện ứng dụng.
RepeatedField triển khai
IList<T>
.
Có hai cách để điền vào trường RepeatedField.
Phiên bản C# cũ hơn: Thêm giá trị bằng phương pháp Addrange
Dưới đây là ví dụ minh hoạ.
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" }
});
Phiên bản C# mới hơn: Sử dụng cú pháp trình khởi tạo bộ sưu tập
// 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 }
};
Loại OneOf
Một số trường trong API Google Ads được đánh dấu là trường OneOf, tức là trường đó
có thể giữ nhiều loại khác nhau nhưng chỉ có một giá trị tại một thời điểm nhất định. Các trường OneOf là
tương tự như kiểu hợp nhất trong C.
Thư viện .NET triển khai các trường OneOf bằng cách cung cấp một thuộc tính cho mỗi loại có thể được giữ trong trường OneOf và tất cả thuộc tính cập nhật trường lớp dùng chung.
Ví dụ: campaign_bidding_strategy của chiến dịch được đánh dấu là OneOf
. Lớp này được triển khai như sau (mã đơn giản để ngắn gọn):
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_; }
}
}
Vì các tài sản OneOf dùng chung bộ nhớ, nên một bài tập có thể ghi đè một bài tập trước đó bài tập, dẫn đến các lỗi nhỏ. Ví dụ:
Campaign campaign = new Campaign()
{
ManualCpc = new ManualCpc()
{
EnhancedCpcEnabled = true
},
ManualCpm = new ManualCpm()
{
}
};
Trong trường hợp này, campaign.ManualCpc hiện là null kể từ khi khởi tạo
Trường campaign.ManualCpm ghi đè hoạt động khởi tạo trước đó của
campaign.ManualCpc.
Chuyển đổi sang các định dạng khác
Bạn có thể dễ dàng chuyển đổi các đối tượng protobuf sang định dạng JSON và đảo ngược. Đây là hữu ích khi xây dựng những hệ thống cần giao tiếp với các hệ thống khác yêu cầu dữ liệu ở định dạng dựa trên văn bản như JSON hoặc 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);
Bạn cũng có thể chuyển đổi tuần tự một đối tượng thành các byte và ngược lại. Chuyển đổi tuần tự nhị phân khác hiệu quả bộ nhớ và lưu trữ hơn định dạng 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);