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 (field mask) 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 (field mask) sẽ bị bỏ qua, ngay cả khi được gửi đến máy chủ.
Tiện íchfieldMasks
Bạn nên dùng tiện ích mặt nạ trường (field mask) tích hợp sẵn của chúng tôi (FieldMasks
) để tạo mặt nạ trường. Nhờ vậy, bạn có thể 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:
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
status => PAUSED,
networkSettings =>
Google::Ads::GoogleAds::V16::Resources::NetworkSettings->new({
targetSearchNetwork => "false"
})
});
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => all_set_fields_of($campaign)
});
Trước tiên, ví dụ này sẽ tạo một đối tượng Campaign
bằng cách đặt tên tài nguyên của đối tượng đó
bằng cách sử dụng tiện ích ResourceNames
, để 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::all_set_fields_of()
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ể truyền trực tiếp mặt nạ được trả về đến lệnh gọi cập nhật.
FieldMasks::all_set_fields_of()
là một phương thức thuận tiện cho FieldMasks::field_mask()
.
Đối tượng này so sánh đối tượng đã truyền của bạn với một đối tượng trống thuộc cùng một lớp. Vì vậy, trong mã ở trên, bạn cũng có thể sử dụng
field_mask(Google::Ads::GoogleAds::V16::Resources::Campaign->new({}), $campaign)
thay vì all_set_fields_of($campaign)
.
Tạo mặt nạ theo cách thủ công
Để tạo mặt nạ trường từ đầu, trước tiên, bạn cần tạo đối tượng Google::Ads::GoogleAds::Common::FieldMask
, sau đó tạo tham chiếu mảng được điền sẵn tên của mọi trường mà bạn định thay đổi và cuối cùng là chỉ định tham chiếu mảng cho trường paths
của mặt nạ trường.
my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
paths => ["status", "name"]
});
Cập nhật các trường đối tượng và trường phụ của các trường đó
Các trường đối tượng 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 đối tượng chưa được xác định trường phụ
Một trường đối tượng trong Perl tương đương với một protobuf MESSAGE
trong các thư viện ứng dụng chạy trên gRPC. Khi cập nhật một trường đối tượng không được xác định bằng bất kỳ trường phụ nào, hãy sử dụng tiện ích Trường Mặt nạ để tạo mặt nạ trường, như mô tả ở trên.
Các trường đối tượng có trường phụ được xác định
Khi cập nhật một trường đối tượng được xác định bằng các trường phụ mà không đặt rõ ràng bất kỳ trường phụ nào trên thông báo đó, bạn phải tự thêm từng trường con đối tượng có thể biến đổ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 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 all_set_fields_of()
và field_mask()
của tiện íchFieldMasks sẽ không đạt được mục tiêu như mong đợi.
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
.
# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName =>
Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
maximizeConversions =>
Google::Ads::GoogleAds::V16::Resources::MaximizeConversions->new()
});
# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask will include 'maximize_conversions',
# which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => all_set_fields_of($campaign)
});
# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
customerId => $customer_id,
operations => [$campaign_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.
# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
)
});
# 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.
# 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
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";
# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => $field_mask
});
Xoá trường
Bạn có thể xoá các trường một cách rõ ràng bằng cách thêm các trường đó vào mặt nạ trường (field mask) như minh hoạ ở trên hoặc bằng cách đặt trường đó thành một giá trị trống hoặc không xác định. 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 bằng giá trị lớn hơn
0
.
# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
Google::Ads::GoogleAds::V16::Resources::Campaign->new({
resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
),
maximizeConversions => Google::Ads::GoogleAds::V16::Resources::MaximizeConversions->new({
targetCpaMicros => 0
})
});
# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask, which will include 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
Google::Ads::GoogleAds::V16::Services::CampaignService::CampaignOperation->new({
update => $campaign,
updateMask => all_set_fields_of($campaign)
});
Lưu ý rằng bạn chỉ có thể xoá các trường có trường phụ lồng nhau bằng cách xoá từng trường con riêng lẻ, như minh hoạ trong phần Các trường đối tượng có trường con được xác định.