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. Danh sách mặt nạ trường tất cả các trường mà bạn dự định thay đổi trong bản 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 dùng mặt nạ trường tích hợp sẵn theo cách đề xuất để tạo mặt nạ trường tiện ích, cho phép bạn tạo mặt nạ trường từ đối tượng đã sửa đổi thay vì xây dựng chúng từ đầu.
Dưới đây là ví dụ về cách cập nhật chiến dịch:
// Creates a Campaign object with the proper resource name and any other changes.
Campaign campaign =
Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.setStatus(CampaignStatus.PAUSED)
.build();
// Constructs an operation that will update the campaign, using the FieldMasks'
// allSetFieldsOf utility to derive the update mask. This mask tells the Google
// Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
.build();
// Sends the operation in a mutate request.
MutateCampaignsResponse response =
campaignServiceClient.mutateCampaigns(
customerId.toString(), Collections.singletonList(operation));
Ví dụ này trước tiên sẽ tạo một đối tượng Campaign
trống rồi đặt tài nguyên của đối tượng đó
để API biết chiến dịch nào đang được cập nhật.
Ví dụ này sử dụng phương thức FieldMasks.allSetFieldsOf()
trên chiến dịch để
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ể
trực tiếp truyền mặt nạ được trả về đến lệnh gọi cập nhật.
Nếu cần làm việc với một đối tượng hiện có để cập nhật một số trường, bạn có thể sửa đổi mã như sau:
Campaign existingCampaign;
// Obtains existingCampaign from elsewhere.
...
// Creates a new campaign based off the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
existingCampaign.toBuilder()
.setStatus(CampaignStatus.PAUSED)
.build();
// Constructs an operation that will update the campaign, using the FieldMasks'
// compare utility to derive the update mask. This mask tells the Google Ads API
// which attributes of the campaign you want to change.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaignToUpdate)
.setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
.build();
// Sends the operation in a mutate request.
MutateCampaignsResponse response =
campaignServiceClient.mutateCampaigns(
customerId.toString(), Collections.singletonList(operation));
Để tạo một mặt nạ trường từ đầu, trước tiên, bạn sẽ tạo một
FieldMask
Đối tượng, sau đó thêm tên của từng trường bạn định thay đổi thành
.
FieldMask fieldMask =
FieldMask.newBuilder()
.addPaths("status")
.addPaths("name")
.build();
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 thuộc tính:
target_cpa_micros
,
cpc_bid_ceiling_micros
và cpc_bid_floor_micros
) hoặc không thể không có
(chẳng hạn như ManualCpm
).
Trường thông báo không có trường phụ được 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
FieldMaskUtil để tạo mặt nạ trường, như mô tả ở trên.
Trường thông báo có trường phụ được xác định
Khi cập nhật trường MESSAGE
được xác định bằng các trường phụ không có
cài đặt rõ ràng bất kỳ trường phụ nào trên thông báo đó, bạn phải tự mình
thêm từng trường con MESSAGE
có thể thay đổi vào FieldMask
, tương tự như
ví dụ ở trên để 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
của các trường trên chiến lược đặt giá thầu mới. Ví dụ dưới đây minh hoạ cách
hãy cập nhật chiến dịch để sử dụng
MaximizeConversions
chiến lược đặt giá thầu
mà không cần thiết lập bất kỳ trường phụ nào trong 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à compare()
của phương thức
FieldMaskUtil không đạt được mục tiêu đề ra.
Ví dụ sau đây sẽ tạo một mặt nạ trường bao gồm
maximize_conversions
. Tuy nhiên, API Google Ads không cho phép hành vi này
ngăn chặn việc vô tình xoá các trường và tạo ra
FieldMaskError.FIELD_HAS_SUBFIELDS
.
// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.setMaximizeConversions(MaximizeConversions.newBuilder().build())
.build();
// 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 =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
.build();
// 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 =
campaignServiceClient.mutateCampaigns(
customerId.toString(), Collections.singletonList(operation));
Ví dụ sau đây minh hoạ cách cập nhật một chiến dịch đúng cách để sử dụng
MaximizeConversions
chiến lược đặt giá thầu mà không đặt bất kỳ trường phụ nào.
// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.build();
// Creates a field mask from the existing campaign and adds all of the mutable
// fields (only one in this case) on the MaximizeConversions bidding strategy to
// the field mask. Because this field is 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 without any of its subfields
// set.
FieldMask fieldMask = FieldMasks.allSetFieldsOf(campaign)
.toBuilder()
// 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
.addPaths("maximize_conversions.target_cpa_micros")
.build();
// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(fieldMask)
.build();
Xoá 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 rõ ràng các trường này vào mặt nạ trường. 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à chiến dịch
Trường target_cpa_micros
được đặt có giá trị lớn hơn 0.
Đoạn mã sau đây chạy; tuy nhiên, maximize_conversions.target_cpa_micros
sẽ không được thêm vào mặt nạ trường nên sẽ không có thay đổi nào đối với
Trường target_cpa_micros
:
// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0.
Campaign campaign =
Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.setMaximizeConversions(
MaximizeConversions.newBuilder().setTargetCpa(0).build())
.setStatus(CampaignStatus.PAUSED)
.build();
// 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 =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
.build();
// 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 =
campaignServiceClient.mutateCampaigns(
customerId.toString(), Collections.singletonList(operation));
Ví dụ tiếp theo minh hoạ cách xoá target_cpa_micros
đúng cách
trên chiến lược đặt giá thầu MaximizeConversions
.
// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
.setResourceName(ResourceNames.campaign(customerId, campaignId))
.build();
// 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)
.toBuilder()
.addPaths("maximize_conversions.target_cpa_micros")
.build();
// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
CampaignOperation.newBuilder()
.setUpdate(campaign)
.setUpdateMask(fieldMask))
.build();
Lưu ý rằng giá trị "không chính xác" ví dụ ở trên có hoạt động như dự kiến cho các trường
được xác định là optional
trong API Google Ads
protocol buffers
.
Nhưng vì
target_cpa_micros
không phải là trường optional
, trường "không chính xác" Ví dụ này không cập nhật
để xoá trường target_cpa
.