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

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 trong đó 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 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 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ó thể đọc.

Ví dụ: trường url_custom_parameters của một chiến dịch là trường lặp lại, do đó, trường đó sẽ đượ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ó 2 cách để điền trường RepeatedField.

Phiên bản C# cũ hơn: Thêm giá trị bằng phương thức AddRange

Hãy xem ví dụ dưới đây.

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, nghĩa là trường này 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 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 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 nhiệm vụ có thể ghi đè nhiệm vụ chỉ định 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 đè hoạt động khởi động 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 những hệ thống cần giao tiếp với các hệ thống khác đòi hỏi 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 rồi ngược lại. 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);