Khẩu trang tại chỗ

Trong API Google Ads, quá trình cập nhật được thực hiện bằng cách sử dụng mặt nạ trường (field mask). Mặt nạ trường liệt kê tất cả các trường bạn dự định thay đổi trong quá trình cập nhật và mọi trường được chỉ định không có trong mặt nạ trường sẽ bị bỏ qua, ngay cả khi được gửi đến máy chủ.

FieldMaskUtil

Bạn nên tạo mặt nạ cho trường (field mask) bằng cách sử dụng tiện ích mặt nạ trường (field mask) tích hợp sẵn của chúng tôi. Tiện ích 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.

Dưới đây là ví dụ về cách cập nhật chiến dịch:

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

Trước tiên, chúng ta sẽ tạo một đối tượng Campaign trống. Sau đó, chúng tôi đặt tên tài nguyên để API biết chính xác chiến dịch mà chúng tôi đang cập nhật.

Ví dụ này sử dụng phương thức FieldMasks.AllSetFieldsOf trên chiến dịch sẽ tự động tạo một 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ạ được trả về đến lệnh gọi cập nhật.

Đôi khi, bạn có thể cần phải 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, bạn nên sửa đổi mã như sau:

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

Để tạo mặt nạ trường từ đầu, trước tiên, bạn cần tạo đối tượng FieldMask, sau đó tạo một mảng được điền sẵn tên của mọi trường mà bạn định thay đổi, cuối cùng thêm nội dung mảng vào trường Path của mặt nạ trường.

FieldMask fieldMask = new FieldMask();
fieldMask.Paths.AddRange(new string[] { "status", "name" });

Cập nhật các trường thông báo và trường phụ của các trường đó

Các trường MESSAGE có thể có các trường phụ (chẳng hạn như MaximizeConversions có 3 trường: target_cpa_micros, cpc_bid_ceiling_micros và cpc_bid_floor_micros) hoặc hoàn toàn không có trường phụ nào (chẳng hạn như ManualCpm).

Các trường thông báo chưa có trường phụ xác định

Khi cập nhật trường MESSAGE không được xác định bằng bất kỳ trường phụ nào, hãy sử dụng FieldMasks để tạo mặt nạ trường, như mô tả ở trên.

Các trường thông báo có trường phụ xác định

Khi cập nhật trường MESSAGE được xác định bằng các trường phụ mà không đặt rõ ràng bất kỳ trường con nào trên thông báo đó, bạn phải thêm từng trường con MESSAGE có thể biến đổi vào FieldMask theo cách thủ công, tương tự như ví dụ trên giúp tạo mặt nạ trường từ đầu.

Một ví dụ phổ biến là cập nhật chiến lược đặt giá thầu của chiến dịch mà không đặt bất kỳ trường nào trên chiến lược đặt giá thầu mới. Ví dụ bên dưới minh hoạ cách cập nhật một chiến dịch để sử dụng chiến lược đặt giá thầu MaximizeConversions mà không cần đặt bất kỳ trường phụ nào cho chiến lược đặt giá thầu.

Trong trường hợp này, việc sử dụng phương thức AllSetFieldsOf() và FromChanges() của FieldMasks sẽ không đạt được mục tiêu mong muốn.

Ví dụ sau đây sẽ tạo một mặt nạ cho trường (field mask) chứa maximize_conversions. Tuy nhiên, API Google Ads không cho phép hành vi này để ngăn việc vô tình xoá các trường và tạo ra lỗi FieldMaskError.FIELD_HAS_SUBFIELDS.

Cảnh báo: Mã sau đây tạo ra lỗi.

// 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()
};

// Constructs an operation, using the FieldMasks' AllSetFieldsOf utility to
// derive the update mask. The field mask will include 'maximize_conversions`,
// which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that will result in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
// be included in a field mask.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

Ví dụ sau minh hoạ cách cập nhật chiến dịch đúng cách để sử dụng chiến lược đặt giá thầu MaximizeConversions mà không cần đặt bất kỳ trường phụ nào.

Thành công: Mã bên dưới đã cập nhật thành công chiến lược đặt giá thầu của chiến dịch.

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

// Creates a field mask from the existing campaign and adds all of the fields
// on the MaximizeConversions bidding strategy to the field mask. Because these
// fields are included in the field mask but excluded from the campaign object,
// the Google Ads API will set the campaign's bidding strategy to a
// MaximizeConversions object with none of its subfields set.
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
};

Xoá các trường

Bạn có thể xoá một số trường một cách rõ ràng. Tương tự như ví dụ trên, bạn phải thêm các trường này một cách rõ ràng vào mặt nạ trường (field mask). Ví dụ: giả sử bạn có một chiến dịch sử dụng chiến lược đặt giá thầu MaximizeConversions và trường target_cpa_micros được đặt với giá trị lớn hơn 0.

Các mã sau đây sẽ chạy; tuy nhiên, maximize_conversions.target_cpa_micros sẽ không được thêm vào mặt nạ cho trường (field mask), nên sẽ không có thay đổi nào đối với trường target_cpa_micros:

Cảnh báo: Mã này không gây ra lỗi, nhưng target_cpa_micros của chiến lược đặt giá thầu MaximizeConversions sẽ không bị xoá.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set 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 });

Ví dụ tiếp theo minh hoạ cách xoá đúng trường target_cpa_micros trong chiến lược đặt giá thầu MaximizeConversions.

Thành công: Mã sau đây đã xoá target_cpa_micros.

// 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
};

Xin lưu ý rằng ví dụ "không chính xác" ở trên hoạt động đúng như dự kiến cho các trường được xác định là optional trong API Google Ads protocol buffers. Tuy nhiên, vì target_cpa_micros không phải là một trường optional, nên ví dụ "không chính xác" sẽ không cập nhật chiến lược đặt giá thầu để xoá trường target_cpa.

Lưu ý quan trọng: Nếu bạn có ý định xoá một trường, thì cách an toàn nhất để đạt được mục tiêu này là thêm trường đó vào mặt nạ cho trường một cách rõ ràng.