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

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

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

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

    $campaign = new Campaign([
        'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
        'status' => CampaignStatus::PAUSED
    ]);

    $campaignOperation = new CampaignOperation();
    $campaignOperation->setUpdate($campaign);
    $campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

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

จากนั้นโค้ดจะสร้างออบเจ็กต์ CampaignOperation และตั้งค่า สร้างแคมเปญไว้ หลังจากนั้นจะใช้ FieldMasks::allSetFieldsOf() เพื่อสร้างฟิลด์มาสก์สำหรับแคมเปญโดยใช้ฟิลด์ที่เปลี่ยนแปลงทั้งหมด ในที่สุด จะส่งมาสก์ที่แสดงผลไปยังออบเจ็กต์การดำเนินการของแคมเปญ

โปรดทราบว่า FieldMasks::allSetFieldsOf เป็นวิธีที่สะดวกสำหรับ FieldMasks::compare() โดยจะเปรียบเทียบออบเจ็กต์ที่คุณส่งกับออบเจ็กต์ว่างของคลาสเดียวกัน สำหรับ ในโค้ดก่อนหน้านี้ คุณอาจใช้ FieldMasks::compare(new Campaign(), $campaign) แทน allSetFieldsOf()

การอัปเดตฟิลด์ข้อความและฟิลด์ย่อย

MESSAGE ช่องสามารถมีช่องย่อยได้ (เช่น MaximizeConversions ซึ่งมี 3 ส่วน: target_cpa_micros, cpc_bid_ceiling_micros และ cpc_bid_floor_micros) หรือไม่ต้องไม่มีรายการใดๆ เลย (เช่น ManualCpm)

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

เมื่ออัปเดตช่อง MESSAGE ที่ไม่ได้กำหนดด้วยช่องย่อยใดๆ ให้ใช้ FieldMasks เพื่อสร้างฟิลด์มาสก์ ตามที่อธิบายไว้ก่อนหน้านี้

ช่องข้อความที่มีช่องย่อยที่กำหนด

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

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

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

โค้ดต่อไปนี้จะสร้างมาสก์ของช่องที่มี maximize_conversions อย่างไรก็ตาม Google Ads API ไม่อนุญาตพฤติกรรมดังกล่าวเพื่อป้องกัน การล้างฟิลด์โดยไม่ได้ตั้งใจและสร้าง FieldMaskError.FIELD_HAS_SUBFIELDS

คำเตือน: โค้ดต่อไปนี้เกิดข้อผิดพลาด

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions()
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. The field mask will include 'maximize_conversions`,
// which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// 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.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);

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

สำเร็จ: โค้ดด้านล่างอัปเดตกลยุทธ์การเสนอราคาของแคมเปญเรียบร้อยแล้ว

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// Creates a field mask from the existing campaign and adds all of the mutable
// fields (only one in this case) 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 will set the campaign's
// bidding strategy to a MaximizeConversions object without any of its subfields
// set.
fieldMask = FieldMasks::allSetFieldsOf($campaign);
// 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
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['maximize_conversions.target_cpa_micros']
));

// Creates an operation to update the campaign with the specified fields.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

กำลังล้างข้อมูลในช่อง

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

การเรียกใช้โค้ดต่อไปนี้ อย่างไรก็ตาม maximize_conversions.target_cpa_micros จะไม่เพิ่มลงในมาสก์ของช่อง จึงไม่มีการเปลี่ยนแปลงใดๆ ช่อง target_cpa_micros:

คำเตือน: โค้ดนี้จะไม่ทำให้เกิดข้อผิดพลาด แต่ target_cpa_micros ของกลยุทธ์การเสนอราคา MaximizeConversions จะไม่ถูกล้าง

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions(['target_cpa' => 0]),
    'status' => CampaignStatus::PAUSED
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because
// 'maximize_conversions.target_cpa_micros' was not included in the field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);

โค้ดต่อไปนี้แสดงวิธีล้าง target_cpa_micros อย่างถูกต้อง ในกลยุทธ์การเสนอราคา MaximizeConversions

สำเร็จ: รหัสต่อไปนี้ล้าง target_cpa_micros

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
$fieldMask = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['maximize_conversions.target_cpa_micros']
));

// Creates an operation to update the campaign with the specified field.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

โปรดทราบว่าลิงก์ที่ "ไม่ถูกต้อง" โค้ดทำงานได้อย่างที่ควรจะเป็นสำหรับช่อง เป็น optional ใน Google Ads API protocol buffers แต่ตั้งแต่ target_cpa_micros ไม่ใช่ช่อง optional แสดงว่า "ไม่ถูกต้อง" โค้ดจะไม่อัปเดต กลยุทธ์การเสนอราคาเพื่อล้างฟิลด์ target_cpa

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