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 một số quy ước và loại Protobuf khi làm việc với API này.

Trường tuỳ chọn

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ới trường hợp 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 chúng cũng cung cấp các phương thức bổ sung để xoá trường và kiểm tra xem trường có được đặt hay không.

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 để 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ảng trường được biểu thị trong API Google Ads dưới dạng RepeatedField chỉ có thể đọc.

Ví dụ: trường url_custom_parameters của chiến dịch là một trường lặp lại, vì vậy, trường này được biểu thị dưới dạng RepeatedField<CustomParameter> chỉ có thể đọ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ũ: Thêm giá trị bằng phương thức AddRange

Sau đây là ví dụ.

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ác phiên bản C# mới hơn: Sử dụng cú pháp trình khởi tạo tập hợ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, nghĩa là trường này có thể chứa nhiều loại nhưng chỉ một giá trị tại một thời điểm nhất định. Các trường OneOf tương tự như loại union 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 lưu giữ trong trường OneOf và tất cả các thuộc tính cập nhật mộ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ã được đơn giản hoá để 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 lượt gán có thể ghi đè một lượt gán 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 tạo trường campaign.ManualCpm sẽ ghi đè quá trình 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à ngược lại. Điều này rất hữu ích khi xây dựng các 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 byte và ngược lại. Quá trình chuyển đổi tuần tự nhị phân hiệu quả hơn về bộ nhớ và dung lượng lưu trữ 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);