ใน Google Ads API การอัปเดตจะทำโดยใช้ฟิลด์มาสก์ ฟิลด์มาสก์จะแสดงช่องทั้งหมดที่คุณตั้งใจจะเปลี่ยนแปลงเมื่อมีการอัปเดต และระบบจะไม่สนใจช่องที่ระบุซึ่งไม่ได้อยู่ในมาสก์ของช่อง แม้ว่าจะส่งไปที่เซิร์ฟเวอร์ก็ตาม
ยูทิลิตี FieldMasks
วิธีที่แนะนำในการสร้างมาสก์ฟิลด์คือการใช้ยูทิลิตีฟิลด์มาสก์ในตัว (FieldMasks
) ที่ให้คุณสร้างมาสก์ฟิลด์จากวัตถุที่แก้ไขแล้ว แทนที่จะสร้างตั้งแต่ต้น
ตัวอย่างการอัปเดตแคมเปญมีดังนี้
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)
});
ตัวอย่างนี้จะสร้างออบเจ็กต์ Campaign
ก่อนโดยตั้งชื่อทรัพยากรโดยใช้ยูทิลิตี ResourceNames
เพื่อให้ API รู้ว่ากำลังอัปเดตแคมเปญใด
ตัวอย่างนี้ใช้เมธอด FieldMasks::all_set_fields_of()
ในแคมเปญเพื่อสร้างมาสก์ฟิลด์ที่แจกแจงช่องของชุดทั้งหมดโดยอัตโนมัติ จากนั้นคุณจะส่งมาสก์ที่ได้รับไปยังการเรียกใช้การอัปเดตได้โดยตรง
FieldMasks::all_set_fields_of()
เป็นวิธีการที่สะดวกสำหรับ FieldMasks::field_mask()
โดยจะเปรียบเทียบออบเจ็กต์ที่ส่งผ่านกับออบเจ็กต์ว่างของคลาสเดียวกัน ดังนั้น ในโค้ดด้านบน
คุณยังสามารถใช้
field_mask(Google::Ads::GoogleAds::V16::Resources::Campaign->new({}), $campaign)
แทน all_set_fields_of($campaign)
การสร้างมาสก์ด้วยตนเอง
หากต้องการสร้างมาสก์ของช่องตั้งแต่ต้น คุณต้องสร้างออบเจ็กต์ Google::Ads::GoogleAds::Common::FieldMask
จากนั้นสร้างการอ้างอิงอาร์เรย์ที่มีชื่อของช่องทั้งหมดที่คุณต้องการเปลี่ยนแปลง และสุดท้ายกำหนดการอ้างอิงอาร์เรย์ให้กับช่อง paths
ของมาสก์ฟิลด์
my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
paths => ["status", "name"]
});
การอัปเดตช่องออบเจ็กต์และช่องย่อย
ช่องออบเจ็กต์อาจมีช่องย่อย (เช่น MaximizeConversions
ซึ่งมี 3 ช่อง ได้แก่ target_cpa_micros
, cpc_bid_ceiling_micros
และ cpc_bid_floor_micros
) หรืออาจไม่มีช่องย่อยเลย (เช่น ManualCpm
)
ช่องออบเจ็กต์ที่ไม่มีช่องย่อยที่กำหนด
ช่องออบเจ็กต์ใน Perl เทียบเท่ากับ Protobuf MESSAGE
ในไลบรารีของไคลเอ็นต์ที่ทำงานบน gRPC เมื่ออัปเดตช่องออบเจ็กต์ที่ไม่ได้กำหนดด้วยช่องย่อย ให้ใช้ยูทิลิตี FieldMasks เพื่อสร้างฟิลด์มาสก์ตามที่อธิบายไว้ข้างต้น
ช่องออบเจ็กต์ที่มีช่องย่อยที่กำหนด
เมื่ออัปเดตช่องออบเจ็กต์ที่มีการระบุช่องย่อยโดยไม่ได้ตั้งค่าช่องย่อยใดๆ ในข้อความนั้นอย่างชัดแจ้ง คุณจะต้องเพิ่มช่องย่อยของออบเจ็กต์ที่เปลี่ยนแปลงได้แต่ละช่องด้วยตนเองลงใน FieldMask
ด้วยตนเอง ซึ่งคล้ายกับตัวอย่างด้านบนที่สร้างมาสก์ของช่องตั้งแต่ต้น
ตัวอย่างหนึ่งที่พบบ่อยคือการอัปเดตกลยุทธ์การเสนอราคาของแคมเปญโดยไม่ตั้งค่าช่องใดๆ ในกลยุทธ์การเสนอราคาใหม่ ตัวอย่างด้านล่างแสดงวิธีอัปเดตแคมเปญให้ใช้กลยุทธ์การเสนอราคา MaximizeConversions
โดยไม่ต้องตั้งค่าช่องย่อยในกลยุทธ์การเสนอราคา
ในกรณีนี้ การใช้เมธอด all_set_fields_of()
และ field_mask()
ของยูทิลิตี FieldMasks ไม่บรรลุเป้าหมายที่ต้องการ
ตัวอย่างต่อไปนี้สร้างฟิลด์มาสก์ที่มี maximize_conversions
อย่างไรก็ตาม Google Ads API ไม่อนุญาตการทำงานลักษณะนี้ เพื่อป้องกันการล้างช่องโดยไม่ได้ตั้งใจและสร้างข้อผิดพลาด 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]
});
ตัวอย่างต่อไปนี้แสดงวิธีอัปเดตแคมเปญอย่างถูกต้องเพื่อใช้กลยุทธ์การเสนอราคา MaximizeConversions
โดยไม่ต้องตั้งค่าช่องย่อย
# 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
});
การล้างข้อมูลช่อง
คุณล้างช่องอย่างชัดแจ้งได้โดยเพิ่มลงในมาสก์ช่องดังที่แสดงด้านบน หรือโดยตั้งค่าช่องเป็นค่าว่างหรือค่าที่ไม่ได้กำหนด ตัวอย่างเช่น สมมติว่าคุณมีแคมเปญที่ใช้กลยุทธ์การเสนอราคา MaximizeConversions
และกำหนดค่าช่อง target_cpa_micros
ด้วยค่าที่มากกว่า 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)
});
โปรดทราบว่าคุณจะล้างช่องที่มีช่องย่อยที่ซ้อนกันได้ด้วยการล้างช่องย่อยแต่ละช่องเท่านั้น ดังที่แสดงในช่องออบเจ็กต์ที่มีช่องย่อยที่กําหนดไว้