ใน Google Ads API การอัปเดตจะทำโดยใช้ฟิลด์มาสก์ ฟิลด์มาสก์จะแสดงช่องทั้งหมดที่คุณตั้งใจจะเปลี่ยนแปลงเมื่อมีการอัปเดต และระบบจะไม่สนใจช่องที่ระบุซึ่งไม่ได้อยู่ในมาสก์ของช่อง แม้ว่าจะส่งไปที่เซิร์ฟเวอร์ก็ตาม
FieldMaskUtil
วิธีที่แนะนำในการสร้างมาสก์ฟิลด์คือการใช้ยูทิลิตีฟิลด์มาสก์ในตัวซึ่งจะซ่อนรายละเอียดเฉพาะจำนวนมาก และช่วยให้คุณสร้างมาสก์ของช่องได้โดยอัตโนมัติด้วยการตรวจสอบการเปลี่ยนแปลงที่คุณทำในช่องของเอนทิตี
วิธีสร้างมาสก์ฟิลด์สำหรับการอัปเดตแคมเปญมีดังนี้
campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)
mask = client.field_mask.with campaign do
campaign.status = :PAUSED
campaign.network_settings = client.resource.network_settings do |ns|
ns.target_search_network = false
end
end
โค้ดจะสร้างออบเจ็กต์แคมเปญที่ว่างเปล่าก่อน จากนั้นตั้งชื่อทรัพยากรเพื่อแจ้ง API ของแคมเปญที่กำลังอัปเดต
ตัวอย่างนี้ใช้เมธอด client.field_mask.with
ในแคมเปญเพื่อเริ่มการบล็อกที่ครอบคลุมการอัปเดต ในตอนท้ายของการบล็อกนี้ ยูทิลิตีจะเปรียบเทียบสถานะปัจจุบันของแคมเปญหลังการบล็อกกับสถานะเริ่มต้นของแคมเปญก่อนบล็อก และสร้างมาสก์ฟิลด์ที่ระบุช่องที่เปลี่ยนแปลงโดยอัตโนมัติ คุณระบุฟิลด์มาสก์ดังกล่าวให้กับการดำเนินการได้เมื่อสร้างฟิลด์สำหรับการเรียกใช้การเปลี่ยนแปลง ดังนี้
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
แนะนำให้ใช้วิธีนี้เมื่อคุณดำเนินการที่ซับซ้อนและต้องการควบคุมทุกขั้นตอนอย่างละเอียด แต่ในกรณีส่วนใหญ่ คุณสามารถใช้ยูทิลิตีไลบรารี Ruby ที่ง่ายขึ้นได้ เช่น
operation = client.operation.update_resource.campaign do |c|
c.status = :PAUSED
c.network_settings = client.resource.network_settings do |ns|
ns.target_search_network = false
end
end
วิธีนี้จะสร้างทรัพยากรแคมเปญที่ว่างเปล่าใหม่โดยอัตโนมัติ สร้างฟิลด์มาสก์ตามการเปลี่ยนแปลงที่คุณทำภายในบล็อก สร้างการดำเนินการอัปเดต และแสดงผลการดำเนินการสุดท้ายที่ป้อนข้อมูล update
และ update_mask
แล้ว คุณยังส่งแคมเปญไปยังเมธอด campaign
เพื่อระบุสถานะเริ่มต้นของแคมเปญได้ด้วย รูปแบบนี้ใช้ได้กับทรัพยากรทั้งหมดที่รองรับการดำเนินการอัปเดต
การสร้างมาสก์ด้วยตนเอง
หากต้องการสร้างมาสก์ฟิลด์ตั้งแต่ต้นโดยไม่ใช้ยูทิลิตีไลบรารีใดๆ คุณจะต้องสร้าง Google::Protobuf::FieldMask
ก่อน จากนั้นสร้างอาร์เรย์ที่มีชื่อของช่องทั้งหมดที่ต้องการเปลี่ยน และกำหนดอาร์เรย์ให้กับช่อง path
ของมาสก์ฟิลด์ในท้ายที่สุด
mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]
การอัปเดตช่องข้อความและฟิลด์ย่อย
ช่อง MESSAGE
อาจมีช่องย่อย (เช่น MaximizeConversions
ซึ่งมี 3 ช่อง ได้แก่ target_cpa_micros
, cpc_bid_ceiling_micros
และ cpc_bid_floor_micros
) หรืออาจไม่มีช่องย่อยเลย (เช่น ManualCpm
)
ช่องข้อความที่ไม่มีฟิลด์ย่อยที่กำหนดไว้
เมื่ออัปเดตช่อง MESSAGE
ที่ไม่ได้กำหนดด้วยฟิลด์ย่อย ให้ใช้ FieldMaskUtill เพื่อสร้างฟิลด์มาสก์ตามที่นำเสนอก่อนหน้านี้
ช่องข้อความที่มีช่องย่อยที่กำหนด
เมื่ออัปเดตช่อง MESSAGE
ที่ระบุด้วยช่องย่อยโดยไม่ได้ตั้งค่าช่องย่อยใดๆ ในข้อความนั้นอย่างชัดแจ้ง คุณจะต้องเพิ่มช่องย่อย MESSAGE
ที่เปลี่ยนแปลงได้แต่ละช่องลงใน FieldMask
ด้วยตนเอง ซึ่งคล้ายกับตัวอย่างก่อนหน้านี้ที่สร้างมาสก์ของช่องไว้ตั้งแต่ต้น
ตัวอย่างหนึ่งที่พบบ่อยคือการอัปเดตกลยุทธ์การเสนอราคาของแคมเปญโดยไม่ได้ตั้งค่าช่องใดก็ตามในกลยุทธ์การเสนอราคาใหม่ ตัวอย่างต่อไปนี้จะแสดงวิธีอัปเดตแคมเปญให้ใช้กลยุทธ์การเสนอราคา MaximizeConversions
โดยไม่ต้องตั้งค่าช่องย่อยในกลยุทธ์การเสนอราคา
สำหรับตัวอย่างนี้ การใช้การเปรียบเทียบ FieldMaskUtill ในตัวไม่ได้บรรลุเป้าหมายที่ต้องการ
โค้ดต่อไปนี้จะสร้างฟิลด์มาสก์ที่มี maximize_conversions
อย่างไรก็ตาม Google Ads API ไม่อนุญาตการทำงานลักษณะนี้เพื่อป้องกันการล้างช่องโดยไม่ได้ตั้งใจและสร้างข้อผิดพลาด FieldMaskError.FIELD_HAS_SUBFIELDS
# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
c.resource_name = client.path.campaign(customer_id, campaign_id)
end
# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
c.maximize_conversions = client.resource.maximize_conversions
end
# 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.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
)
โค้ดต่อไปนี้แสดงวิธีอัปเดตแคมเปญอย่างถูกต้องเพื่อใช้กลยุทธ์การเสนอราคา MaximizeConversions
โดยไม่ต้องตั้งค่าช่องย่อยใดๆ
# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}
# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"
# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
)
การล้างข้อมูลช่อง
คุณล้างช่องบางช่องได้อย่างชัดเจน คุณต้องเพิ่มช่องเหล่านี้ลงในมาสก์ของช่องอย่างชัดแจ้ง คล้ายกับตัวอย่างก่อนหน้านี้ ตัวอย่างเช่น สมมติว่าคุณมีแคมเปญที่ใช้กลยุทธ์การเสนอราคา MaximizeConversions
และตั้งค่าช่อง target_cpa_micros
ด้วยค่าที่มากกว่า 0
โค้ดต่อไปนี้จะทำงาน แต่ระบบจะไม่เพิ่ม maximize_conversions.target_cpa_micros
ลงในมาสก์ของช่อง และจะไม่ทำการเปลี่ยนแปลงใดๆ ในช่อง target_cpa_micros
# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
c.resource_name = client.path.campaign(customer_id, campaign_id)
end
# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
c.maximize_conversions = client.resource.maximize_conversions do |mc|
mc.target_cpa_micros = 0
end
end
# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
end
โค้ดต่อไปนี้แสดงวิธีล้างช่อง target_cpa_micros
ในกลยุทธ์การเสนอราคา MaximizeConversions
อย่างถูกต้อง
# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
c.resource_name = client.path.campaign(customer_id, campaign_id)
c.maximize_conversions = client.resource.maximize_conversions do |mc|
mc.target_cpa_micros = 0
end
end
# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}
# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'
# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
end
โปรดทราบว่าโค้ดที่ "ไม่ถูกต้อง" ทำงานตามที่ควรจะเป็นสำหรับช่องที่กำหนดเป็น optional
ใน Google Ads API protocol buffers
แต่เนื่องจาก target_cpa_micros
ไม่ใช่ช่อง optional
โค้ดที่ "ไม่ถูกต้อง" จึงไม่อัปเดตกลยุทธ์การเสนอราคาเพื่อล้างช่อง target_cpa