การอัปเดตโดยใช้มาสก์ฟิลด์

ใน Google Ads API การอัปเดตจะทำโดยใช้มาสก์ฟิลด์ Field Mask จะแสดงรายการ ฟิลด์ทั้งหมดที่คุณต้องการเปลี่ยนแปลงด้วยการอัปเดต และระบบจะ ไม่สนใจฟิลด์ที่ระบุซึ่งไม่ได้อยู่ใน Field Mask แม้ว่าจะส่งไปยังเซิร์ฟเวอร์ก็ตาม

FieldMaskUtil

วิธีที่แนะนำในการสร้างมาสก์ของฟิลด์คือการใช้ยูทิลิตีมาสก์ของฟิลด์ ในตัวของเรา ซึ่งจะซ่อนรายละเอียดที่เฉพาะเจาะจงจำนวนมากและช่วยให้คุณสร้างมาสก์ของฟิลด์ ได้โดยอัตโนมัติด้วยการตรวจสอบการเปลี่ยนแปลงที่คุณทำกับฟิลด์ของเอนทิตี

ตัวอย่างวิธีสร้าง FieldMask เพื่ออัปเดตแคมเปญ

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 ในแคมเปญเพื่อเริ่ม บล็อกที่ครอบคลุมการอัปเดต เมื่อสิ้นสุดบล็อกนี้ ยูทิลิตีจะเปรียบเทียบสถานะปัจจุบันของแคมเปญหลังบล็อกกับสถานะเริ่มต้นของแคมเปญก่อนบล็อก และสร้างมาสก์ฟิลด์โดยอัตโนมัติซึ่งแสดงรายการฟิลด์ที่เปลี่ยนแปลง คุณระบุมาสก์ฟิลด์ดังกล่าวให้กับ การดำเนินการเมื่อสร้างสำหรับการเรียกใช้ mutate ได้ดังนี้

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 เพื่อ ระบุสถานะเริ่มต้นของแคมเปญได้ด้วย รูปแบบนี้ใช้ได้กับทรัพยากรทั้งหมดที่รองรับการดำเนินการอัปเดต

การสร้างมาสก์ด้วยตนเอง

หากต้องการสร้าง FieldMask จากจุดเริ่มต้นโดยไม่ใช้ยูทิลิตีของไลบรารี คุณ จะต้องสร้าง Google::Protobuf::FieldMask ก่อน จากนั้นสร้างอาร์เรย์ ที่ป้อนชื่อของฟิลด์ทั้งหมดที่คุณต้องการเปลี่ยนแปลง และสุดท้าย กำหนดอาร์เรย์ให้กับฟิลด์ path ของ FieldMask

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 ที่ไม่ได้กำหนดด้วยฟิลด์ย่อยใดๆ ให้ใช้ FieldMaskUtil เพื่อสร้างมาสก์ฟิลด์ตามที่แสดงไว้ก่อนหน้านี้

ฟิลด์ข้อความที่มีฟิลด์ย่อยที่กำหนด

เมื่ออัปเดตฟิลด์ MESSAGE ที่กำหนดด้วยฟิลด์ย่อยโดยไม่ได้ ตั้งค่าฟิลด์ย่อยใดๆ ในข้อความนั้นอย่างชัดเจน คุณต้องเพิ่มฟิลด์ย่อย MESSAGE แต่ละรายการที่เปลี่ยนแปลงได้ลงใน FieldMask ด้วยตนเอง ซึ่งคล้ายกับ ตัวอย่างก่อนหน้านี้ที่สร้างมาสก์ฟิลด์ตั้งแต่ต้น

ตัวอย่างที่พบบ่อยอย่างหนึ่งคือการอัปเดตกลยุทธ์การเสนอราคาของแคมเปญโดยไม่ได้ตั้งค่าฟิลด์ใดๆ ในกลยุทธ์การเสนอราคาใหม่ ตัวอย่างต่อไปนี้ แสดงวิธีอัปเดตแคมเปญให้ใช้กลยุทธ์การเสนอราคา MaximizeConversions โดยไม่ต้องตั้งค่าฟิลด์ย่อยใดๆ ในกลยุทธ์การเสนอราคา

ในตัวอย่างนี้ การใช้การเปรียบเทียบในตัวของ FieldMaskUtil จะไม่ บรรลุเป้าหมายที่ต้องการ

โค้ดต่อไปนี้จะสร้างมาสก์ของช่องที่มี 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กลยุทธ์การเสนอราคาอย่างถูกต้อง

สำเร็จ: โค้ดต่อไปนี้จะล้าง target_cpa_micros

# 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

ประเด็นสำคัญ: หากคุณต้องการล้างช่อง วิธีที่ปลอดภัยที่สุดคือ เพิ่มช่องนั้นลงในมาสก์ของฟิลด์อย่างชัดเจน