Làm việc với các loại Protobuf

Vì API Google Ads sử dụng Protobuf làm định dạng tải trọng mặc định, nên bạn cần hiểu rõ một số loại và quy ước Protobuf khi làm việc với API này.

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 giữa các trường hợp trường có giá trị trống và 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ư các trường thông thường, ngoại trừ việc các trường này cũng cung cấp các phương thức bổ sung để xoá trường và kiểm tra xem trường đó đã được thiết lập hay 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ể dùng các phương thức sau để xử lý 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ưới dạng RepeatedField chỉ đọc.

Ví dụ: trường url_custom_parameters của chiến dịch là trường lặp lại, nên trường này được thể hiện dưới dạng RepeatedField<CustomParameter> chỉ đọc trong thư viện ứng dụng .NET.

RepeatedField triển khai giao diện 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, có nghĩa là trường đó có thể chứa nhiều loại nhưng chỉ có một giá trị tại một thời điểm. Các trường OneOf tương tự như loại 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 giá trị có thể được giữ trong trường OneOf và tất cả cá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à trường 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 thuộc tính OneOf dùng chung bộ nhớ, nên một bài tập có thể ghi đè bài tập trước đó, 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 vì việc khởi chạy trường campaign.ManualCpm sẽ ghi đè thao tác khởi tạo trước đó cho 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. Điều này rất hữu ích khi xây dựng những hệ thống cần giao tiếp với những 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. Quá trình chuyển đổi tuần tự nhị phân có bộ nhớ và dung lượng lưu trữ cao hơn so với đị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);