หน้ากากอนามัย

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

ยูทิลิตี FieldMasks

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

ตัวอย่างการอัปเดตแคมเปญมีดังนี้

my $campaign = Google::Ads::GoogleAds::V21::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => PAUSED,
    networkSettings =>
      Google::Ads::GoogleAds::V21::Resources::NetworkSettings->new({
        targetSearchNetwork => "false"
      })
    });

my $campaign_operation =
  Google::Ads::GoogleAds::V21::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::V21::Resources::Campaign->new({}), $campaign)

แทนที่จะเป็น all_set_fields_of($campaign)

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

หากต้องการสร้าง FieldMask ตั้งแต่ต้น คุณจะต้องสร้างออบเจ็กต์ Google::Ads::GoogleAds::Common::FieldMask ก่อน จากนั้นสร้างการอ้างอิงอาร์เรย์ที่ป้อนชื่อของฟิลด์ทั้งหมด ที่คุณต้องการเปลี่ยนแปลง แล้วสุดท้ายกำหนดการอ้างอิงอาร์เรย์ให้กับฟิลด์ paths ของ FieldMask

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 utility จะไม่บรรลุเป้าหมายที่ต้องการ

ตัวอย่างต่อไปนี้สร้างมาสก์ฟิลด์ที่มี 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::V21::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V21::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::V21::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::V21::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V21::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::V21::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => $field_mask
  });

การล้างช่อง

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

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

# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
  Google::Ads::GoogleAds::V21::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V21::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::V21::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

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