Khẩu trang tại chỗ

Trong API Google Ads, 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 sẽ bị bỏ qua, ngay cả khi được gửi đến máy chủ.

Lớp FieldMaskUtil

Bạn nên sử dụng lớp FieldMaskUtil tích hợp để tạo mặt nạ trường. 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ạ trường 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, bạn sẽ sửa đổi mã để 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 elsewhere.
...

// Create a new campaign based off 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)
};

Cách 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 mà không cần cập nhật bất kỳ trường phụ nào thuộc loại đó. 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 sẽ không thực hiện được do gặp lỗi FieldMaskError.FIELD_HAS_SUBFIELDS. Vì MaximizeConversions có 3 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 đó trong yêu cầu. Tuy nhiên, FieldMaskUtil không thể tạo mặt nạ trường một cách chính xác trong trường hợp này, vì yêu cầu không đặt các trường này.

Trong trường hợp như vậy, bạn có thể chỉnh sửa mặt nạ trường theo cách thủ công như sau:

// 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 here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

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

Cách xoá các trường

API Google Ads hỗ trợ việc xoá một số giá trị trường. Để xoá một trường, bạn phải đặt mặt nạ trường cho trường đó theo cách thủ công. 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 thấy cách xoá trường target_cpa_micros của chiến lược đặt giá thầu MaximizeConversions.

Mã chính xác

Đoạn mã sau đây sẽ xoá trường target_cpa_micros vì chúng ta đang đặt maximize_conversions.target_cpa_micros trong mặt nạ trường và không đặt trường 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 will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.AddRange(new string[] {
    "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 không xoá trường target_cpa_micros vì chúng ta đang đặt trường này thành 0. Cả FieldMaskUtils và máy chủ Google Ads API đều sẽ bỏ qua giá trị này. Ngoài ra, bạn cũng có thể không nhận được lỗi trong trường hợp này, vì giá trị đã bị máy chủ bỏ qua.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object. Attempt 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 the FieldMasks' AllSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because 'maximize_conversions.target_cpa_micros'
// was not included in the field mask.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });