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

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

คลาส FieldMaskUtil

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

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

// Update campaign by setting its status to paused, and "Search network" to false.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    NetworkSettings = new NetworkSettings()
    {
        TargetSearchNetwork = false
    }
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

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

Campaign existingCampaign;

// Obtain existingCampaign from elsewhere.
...

// Create a new campaign based off the existing campaign for update.
Campaign campaignToUpdate = new Campaign(existingCampaign);

// Update campaign by setting its status to paused, and "Search network" to
// false.
campaignToUpdate.Status = CampaignStatus.Paused;
campaignToUpdate.NetworkSettings = new NetworkSettings()
{
    TargetSearchNetwork = false
}

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.FromChanges(existingCampaign, campaignToUpdate)
};

วิธีจัดการข้อผิดพลาด FieldMaskError.FIELD_HAS_SUBFIELDS

ในบางครั้ง คุณอาจต้องตั้งค่าฟิลด์โดยไม่อัปเดตฟิลด์ย่อยของฟิลด์นั้น ลองดูตัวอย่างต่อไปนี้

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
};

CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

การเรียก API นี้จะไม่สำเร็จและแสดงข้อผิดพลาด FieldMaskError.FIELD_HAS_SUBFIELDS เนื่องจาก MaximizeConversions มีฟิลด์ย่อย 3 รายการ เซิร์ฟเวอร์ Google Ads API จึงคาดหวังให้มี Field Mask สำหรับฟิลด์เหล่านั้นอยู่ในคำขอ อย่างไรก็ตาม FieldMaskUtil ไม่สามารถสร้าง Field Mask ได้อย่างถูกต้องในสถานการณ์นี้ เนื่องจากคำขอไม่ได้ตั้งค่าฟิลด์เหล่านี้

ในกรณีดังกล่าว คุณสามารถแก้ไข Field Mask ด้วยตนเองได้ดังนี้

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

FieldMask 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.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

วิธีล้างฟิลด์

Google Ads API รองรับการล้างค่าฟิลด์บางรายการ หากต้องการล้างฟิลด์ คุณต้องตั้งค่า Field Mask สำหรับฟิลด์นั้นด้วยตนเอง การตั้งค่าฟิลด์เป็นค่าเริ่มต้น (เช่น ศูนย์สำหรับฟิลด์ int64) จะไม่ล้างฟิลด์

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

โค้ดที่ถูกต้อง

โค้ดต่อไปนี้จะล้างฟิลด์ target_cpa_micros เนื่องจากเรา ตั้งค่า maximize_conversions.target_cpa_micros ใน Field Mask และ ไม่ได้ตั้งค่าฟิลด์campaign.MaximizeConversions.TargetCpaMicros

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(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 fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

โค้ดไม่ถูกต้อง

โค้ดต่อไปนี้จะไม่ล้าง ฟิลด์ target_cpa_micros เนื่องจากเรา ตั้งค่าฟิลด์นี้เป็นศูนย์ ทั้ง FieldMaskUtils และเซิร์ฟเวอร์ Google Ads API จะไม่สนใจค่านี้ นอกจากนี้ คุณอาจไม่ได้รับข้อผิดพลาดในกรณีนี้ด้วย เนื่องจากเซิร์ฟเวอร์ไม่สนใจค่าดังกล่าว

// Creates a campaign with the proper resource name and a MaximizeConversions
// object. Attempt to clear the target_cpa_micros field by setting it to 0.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
    {
        TargetCpaMicros = 0
    }
};

// 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 operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = 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.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });