หน้ากากภาคสนาม

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

ยูทิลิตี FieldMasks

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

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

use Google::Ads::GoogleAds::Utils::FieldMasks qw(all_set_fields_of field_mask);

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

my $campaign_operation =
  Google::Ads::GoogleAds::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

ตัวอย่างนี้จะสร้างออบเจ็กต์ Campaign ก่อนโดยการตั้งค่าชื่อทรัพยากร โดยใช้ยูทิลิตี ResourceNames เพื่อให้ API ทราบ ว่าแคมเปญใดกำลังได้รับการอัปเดต

ตัวอย่างนี้ใช้เมธอด FieldMasks::all_set_fields_of() ในแคมเปญเพื่อสร้าง Field Mask ที่แสดงรายการช่องที่ตั้งค่าทั้งหมด โดยอัตโนมัติ จากนั้นคุณก็ส่งมาสก์ที่แสดงผลไปยังการเรียกอัปเดตได้โดยตรง

FieldMasks::all_set_fields_of() เป็นเมธอดที่สะดวกสำหรับ FieldMasks::field_mask() โดยจะเปรียบเทียบออบเจ็กต์ที่คุณส่งกับออบเจ็กต์ที่ว่างเปล่าของคลาสเดียวกัน ในโค้ดก่อนหน้า คุณยังใช้โค้ดต่อไปนี้ได้ด้วย

field_mask(
  Google::Ads::GoogleAds::V26::Resources::Campaign->new({}),
  $campaign
)

แทนที่จะใช้ all_set_fields_of($campaign)

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

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

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
  paths => ["status", "name"],
});

อัปเดตช่องออบเจ็กต์และช่องย่อย

ช่องออบเจ็กต์อาจมีช่องย่อย (เช่น MaximizeConversions ซึ่งรวมถึงช่องย่อยอย่าง target_cpa_micros) หรือไม่มีเลย (เช่น ManualCpm)

ช่องออบเจ็กต์ที่ไม่มีช่องย่อยที่กำหนด

ช่องออบเจ็กต์ใน Perl เทียบเท่ากับ MESSAGE ของ protobuf ในไลบรารีของไคลเอ็นต์ที่ทำงานบน gRPC เมื่ออัปเดตช่องออบเจ็กต์ที่ไม่ได้กำหนดด้วยช่องย่อย ให้ใช้ยูทิลิตี FieldMasks เพื่อสร้าง Field Mask ตามที่อธิบายไว้ในส่วนก่อนหน้า

ช่องออบเจ็กต์ที่มีช่องย่อยที่กำหนด

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

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

ในกรณีนี้ การใช้เมธอด all_set_fields_of() และ field_mask() ของยูทิลิตี FieldMasks จะไม่บรรลุเป้าหมายที่ต้องการ

ตัวอย่างต่อไปนี้จะสร้าง Field Mask ที่มี 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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V26::Resources::MaximizeConversions
      ->new(),
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask includes 'maximize_conversions',
# which produces a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

# Sends the operation in a mutate request that results 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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
  });

# Creates a field mask from the existing campaign and adds the mutable subfield
# 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 sets 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.
#
# See the guide on assigning standard and portfolio bidding strategies
# (/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::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => $field_mask,
  });

ล้างช่อง

คุณล้างช่องได้อย่างชัดเจนโดยการเพิ่มช่องลงใน 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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V26::Resources::MaximizeConversions
      ->new({
        targetCpaMicros => 0,
      }),
  });

# Constructs an operation using all_set_fields_of to derive the update mask,
# which includes 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

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