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

Vì Google Ads API sử dụng proto3 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à 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 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 đặt 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ể 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;

Các trường lặp lại

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à 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 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.

Phương thứ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ú pháp của bộ 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 }
};

Trường Oneof

Một số trường trong Google Ads API được đánh dấu là trường oneof, tức 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 nhất định. Các trường oneof tương tự như kiểu hợp trong ngôn ngữ lập trình 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 một trường oneof và tất cả các thuộc tính đều 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à một 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 phép gán có thể ghi đè một phép 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 chạy trường campaign.ManualCpm sẽ ghi đè quá trình khởi chạy trước đó cho campaign.ManualCpc.

Chuyển đổi sang các định dạng khác

Chuyển đổi sang định dạng JSON

Bạn có thể chuyển đổi các đối tượng protobuf sang định dạng JSON và ngược lại. Điều này hữu ích khi bạn xây dựng các 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);

Chuyển đổi thành byte

Bạn có thể chuyển đổi một đối tượng thành byte và ngược lại. Việc chuyển đổi tuần tự nhị phân hiệu quả hơn về bộ nhớ và bộ nhớ 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);