Mặt nạ trường

Trong Google Ads API, mặt nạ trường được dùng để cung cấp danh sách các trường mà một Yêu cầu API sẽ cập nhật. Mọi trường không được chỉ định trong mặt nạ trường đều bị bỏ qua, ngay cả khi được gửi đến máy chủ.

Lớp FieldMasks

Cách được đề xuất để tạo mặt nạ trường trong thư viện ứng dụng .NET là sử dụng lớp tiện ích FieldMasks tích hợp. Lớp này cho phép bạn tạo mặt nạ trường từ một đối tượng đã sửa đổi thay vì tạo mặt nạ từ đầu.

Sau đây là ví dụ về cách cập nhật một chiến dịch sử dụng phương thức FieldMasks.AllSetFieldsOf để tạo một mặt nạ trường liệt kê tất cả các trường được đặt. Sau đó, bạn có thể truyền trực tiếp mặt nạ trường đã tạo vào lệnh gọi cập nhật:

// Update campaign by setting its status to paused, and "Search network" to
// false.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    NetworkSettings = new NetworkSettings()
    {
        TargetSearchNetwork = false
    }
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

Đôi khi, bạn có thể cần làm việc với một đối tượng hiện có và cập nhật một số trường. Trong những trường hợp như vậy, hãy sử dụng phương thức FieldMasks.FromChanges. Phương thức này tạo ra một mặt nạ trường biểu thị sự khác biệt giữa hai đối tượng:

Campaign existingCampaign;

// Obtain existingCampaign from an earlier API call.

// Create a new campaign based on the existing campaign for update.
Campaign campaignToUpdate = new Campaign(existingCampaign);

// Update campaign by setting its status to paused, and "Search network" to
// false.
campaignToUpdate.Status = CampaignStatus.Paused;
campaignToUpdate.NetworkSettings = new NetworkSettings()
{
    TargetSearchNetwork = false
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.FromChanges(existingCampaign, campaignToUpdate)
};

Xử lý lỗi FieldMaskError.FIELD_HAS_SUBFIELDS

Trong một số ít trường hợp, bạn có thể cần đặt một trường thông báo mà không cần cập nhật bất kỳ trường con nào của trường đó. Hãy xem ví dụ sau đây:

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
};

CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

Lệnh gọi API này không thành công do gặp lỗi FieldMaskError.FIELD_HAS_SUBFIELDS. Vì MaximizeConversions có các trường phụ, nên máy chủ Google Ads API dự kiến sẽ có mặt nạ trường cho các trường phụ có thể thay đổi trong yêu cầu. Tuy nhiên, FieldMasks không thể tự động tạo mặt nạ trường phụ trong trường hợp này vì yêu cầu không đặt bất kỳ trường phụ nào.

Trong những trường hợp như vậy, bạn có thể thêm đường dẫn vào fieldMask.Paths theo cách thủ công (đây là một RepeatedField<string>):

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
// Only include 'maximize_conversions.target_cpa_micros' in the field mask
// as it is the only mutable subfield on MaximizeConversions when used as a
// standard bidding strategy.
//
// Learn more about standard and portfolio bidding strategies at:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.Add("maximize_conversions.target_cpa_micros");

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

Xoá các trường

Google Ads API hỗ trợ việc xoá một số giá trị trường. Để xoá một trường, bạn phải tự thêm trường đó vào mặt nạ cho trường trong khi để trống trường trên đối tượng tài nguyên. Việc đặt một trường về giá trị mặc định (chẳng hạn như 0 cho trường int64) sẽ không xoá trường đó.

Ví dụ về mã sau đây cho biết cách xoá trường target_cpa_micros của một chiến lược đặt giá thầu MaximizeConversions:

Mã chính xác

Đoạn mã sau đây xoá trường target_cpa_micros vì đoạn mã này thêm maximize_conversions.target_cpa_micros vào mặt nạ trường mà không đặt thuộc tính campaign.MaximizeConversions.TargetCpaMicros:

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.Add("maximize_conversions.target_cpa_micros");

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

Mã không đúng

Đoạn mã sau đây không xoá trường target_cpa_micros vì đoạn mã này đặt trường thành 0. Cả tiện ích FieldMasks và máy chủ Google Ads API đều bỏ qua giá trị này khi TargetCpaMicros là 0 hoặc khi đường dẫn bị bỏ qua khỏi mặt nạ và máy chủ không trả về lỗi:

// Creates a campaign with the proper resource name and a
// MaximizeConversions object. Attempts to clear the target_cpa_micros
// field by setting it to 0.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
    {
        TargetCpaMicros = 0
    }
};

// Constructs an operation using FieldMasks.AllSetFieldsOf to derive the
// update mask.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that succeeds without clearing
// the previous 'target_cpa_micros' value cleanly.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });