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 cần 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

Bạn nên tạo mặt nạ trường trong thư viện ứng dụng .NET bằng cách sử dụng lớp tiện ích FieldMasks tích hợp sẵn. 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 từ đầu.

Dưới đâ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 nạ trường liệt kê tất cả các trường đã đặ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 vài 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 thể hiện 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 trường thông báo mà không 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 và trả về lỗi FieldMaskError.FIELD_HAS_SUBFIELDS. Vì MaximizeConversions có các trường con, nên máy chủ Google Ads API yêu cầu phải có mặt nạ trường cho các trường con 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 con trong trường hợp này vì yêu cầu không đặt bất kỳ trường con 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 (là RepeatedField<string>) theo cách thủ công:

// 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 thêm trường đó vào mặt nạ trường theo cách thủ công, đồng thời không đặt trường đó trên đối tượng tài nguyên. Việc đặt một trường thành 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 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ì trường này được đặt 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 });