Trong API Google Ads, việc cập nhật được thực hiện bằng cách sử dụng mặt nạ trường. Mặt nạ trường liệt kê tất cả các trường mà bạn dự định thay đổi bằng nội dung 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ủ. Bạn có thể tạo mặt nạ trường theo cách thủ công bằng cách tạo Google\Protobuf\FieldMask
, tạo một mảng được điền sẵn tên của tất cả các trường mà bạn định thay đổi, sau đó gán mảng đó cho trường đường dẫn của mặt nạ trường.
Bạn cũng có thể sử dụng tiện ích mặt nạ trường tích hợp sẵn (FieldMasks). Tiện ích này ẩn nhiều thông tin chi tiết cụ thể và cho phép bạn tự động tạo mặt nạ trường bằng cách theo dõi các thay đổi mà bạn thực hiện đối với các trường của thực thể.
Dưới đây là ví dụ về cách cập nhật chiến dịch:
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
'status' => CampaignStatus::PAUSED
]);
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));
Trước tiên, mã này sẽ tạo một đối tượng Chiến dịch, sau đó đặt tên tài nguyên bằng cách sử dụng ResourceNames
để API biết chiến dịch nào đang được cập nhật. status
cũng được đặt thành PAUSED
.
Sau đó, mã sẽ tạo một đối tượng CampaignOperation
và đặt chiến dịch đã tạo trước đó vào đối tượng đó. Sau đó, hàm này sử dụng FieldMasks::allSetFieldsOf()
để tạo mặt nạ trường cho chiến dịch bằng cách sử dụng tất cả các trường đã thay đổi. Cuối cùng, lớp này sẽ truyền mặt nạ được trả về đến đối tượng thao tác chiến dịch.
Xin lưu ý rằng FieldMasks::allSetFieldsOf
là một phương thức thuận tiện cho FieldMasks::compare()
.
Phương thức này so sánh đối tượng bạn truyền với một đối tượng trống thuộc cùng một lớp. Ví dụ: trong mã trước, bạn có thể sử dụng FieldMasks::compare(new
Campaign(), $campaign)
thay vì allSetFieldsOf()
.
Cập nhật các trường thông báo và trường con của các trường đó
Các trường MESSAGE
có thể có trường con (chẳng hạn như MaximizeConversions
có 3 trường con: target_cpa_micros
, cpc_bid_ceiling_micros
và cpc_bid_floor_micros
) hoặc không có trường con nào (chẳng hạn như ManualCpm
).
Các trường thông báo không có trường con đượ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 con nào, hãy sử dụng FieldMasks
để tạo mặt nạ trường, như mô tả trước đó.
Trường thông báo có các trường con được xác định
Khi cập nhật trường MESSAGE
được xác định bằng các trường con 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ể thay đổi vào FieldMask
theo cách thủ công, tương tự như ví dụ trước đã 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. Mã bên dưới minh hoạ cách cập nhậ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 trên chiến lược đặt giá thầu.
Trong trường hợp này, việc sử dụng các phương thức allSetFieldsOf()
và compare()
của FieldMasks
sẽ không đạt được mục tiêu dự kiến.
Mã 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 để tránh vô tình xoá các trường và tạo lỗi FieldMaskError.FIELD_HAS_SUBFIELDS
.
// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
'maximize_conversions' => 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 = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(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.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);
Mã sau đây minh hoạ cách cập nhật đúng cách 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 con nào.
// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);
// 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 = 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->setPaths(array_merge(
iterator_to_array($fieldMask->getPaths()->getIterator()),
['maximize_conversions.target_cpa_micros']
));
// Creates an operation to update the campaign with the specified fields.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);
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ước, bạn phải thêm các trường này vào mặt nạ trường một cách rõ rà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à trường target_cpa_micros
được đặt giá trị lớn hơn 0
.
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ạ trường, do đó, không có thay đổi nào được thực hiện đố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 = new Campaign([
'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
'maximize_conversions' => new MaximizeConversions(['target_cpa' => 0]),
'status' => CampaignStatus::PAUSED
]);
// 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 = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(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.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);
Mã sau đây minh hoạ cách xoá đúng cách trường target_cpa_micros
trên chiến lược đặt giá thầu MaximizeConversions
.
// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
'resource_name' => ResourceNames::forCampaign($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 = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->setPaths(array_merge(
iterator_to_array($fieldMask->getPaths()->getIterator()),
['maximize_conversions.target_cpa_micros']
));
// Creates an operation to update the campaign with the specified field.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);
Xin lưu ý rằng mã "không chính xác" hoạt động như dự kiến đối với 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à trường optional
, nên mã "không chính xác" không cập nhật chiến lược đặt giá thầu để xoá trường target_cpa
.