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 Bộ đệm giao thức khi làm việc với thư viện ứng dụng .NET.

Trường không bắt buộc

Nhiều trường trong Google Ads API đượ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 trả về giá trị cho trường. Các trường này hoạt động như các thuộc tính 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à optional, 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 the Name field from
// being sent to the server in a subsequent API call.
campaign.ClearName();

// Set the campaign name to an empty string value. This value will be
// sent to the server if you use this object in a subsequent API call.
campaign.Name = "";

// This throws a runtime ArgumentNullException. Use ClearName() instead.
campaign.Name = null;

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

Mảng trường được biểu thị trong Google Ads API 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à 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<T> triển khai giao diện IList<T>.

Có 2 cách để điền sẵn giá trị cho thuộc tính RepeatedField:

Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
};

// Add values to UrlCustomParameters using the AddRange method.
campaign.UrlCustomParameters.AddRange(new CustomParameter[]
{
    new CustomParameter { Key = "season", Value = "christmas" },
    new CustomParameter { Key = "promocode", Value = "NY123" }
});

// 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 kết 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ới tất cả các thuộc tính cập nhật một trường lưu trữ cơ bản 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(),
    ManualCpm = new ManualCpm()
};

Trong trường hợp này, campaign.ManualCpc là null vì việc khởi tạo thuộc tính 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

using Google.Protobuf;

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);

using Google.Protobuf;

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);