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

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

คลาส FieldMasks

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

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

// 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 แทน เมธอดนี้จะสร้างมาสก์ฟิลด์ที่แสดงความแตกต่างระหว่างออบเจ็กต์ 2 รายการ ดังนี้

Campaign existingCampaign;

// Obtain existingCampaign from an earlier API call.

// Create a new campaign based on 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 มีฟิลด์ย่อย เซิร์ฟเวอร์ Google Ads API จึงคาดหวังว่ามาสก์ฟิลด์สำหรับฟิลด์ย่อยที่เปลี่ยนแปลงได้จะแสดงอยู่ในคำขอ อย่างไรก็ตาม FieldMasks ไม่สามารถสร้างมาสก์ช่องย่อยโดยอัตโนมัติในสถานการณ์นี้ได้เนื่องจากคำขอไม่ได้ตั้งค่าช่องย่อยใดๆ

ในกรณีดังกล่าว คุณสามารถเพิ่มเส้นทางไปยัง fieldMask.Paths (ซึ่งเป็น RepeatedField<string>) ด้วยตนเองได้ ดังนี้

// 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 at:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.Add("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 รองรับการล้างค่าบางฟิลด์ หากต้องการล้างฟิลด์ คุณต้องใส่ฟิลด์นั้นในมาสก์ฟิลด์ด้วยตนเองขณะที่ปล่อยฟิลด์นั้นไว้โดยไม่ได้ตั้งค่าในออบเจ็กต์ทรัพยากร การตั้งค่าช่องเป็นค่าเริ่มต้น (เช่น 0 สำหรับช่อง int64) จะไม่ล้างข้อมูลในช่อง

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

รหัสที่ถูกต้อง

โค้ดต่อไปนี้จะล้างช่อง target_cpa_micros เนื่องจากจะเพิ่ม maximize_conversions.target_cpa_micros ลงในมาสก์ช่องโดยไม่ต้องตั้งค่าพร็อพเพอร์ตี้ 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
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.Add("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 เนื่องจากตั้งค่าช่องเป็น 0 ทั้งยูทิลิตี FieldMasks และเซิร์ฟเวอร์ Google Ads API จะไม่สนใจค่านี้เมื่อ TargetCpaMicros เป็น 0 หรือเมื่อละเว้นเส้นทางจากมาสก์ และเซิร์ฟเวอร์จะไม่แสดงข้อผิดพลาด:

// Creates a campaign with the proper resource name and a
// MaximizeConversions object. Attempts 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 FieldMasks.AllSetFieldsOf to derive the
// update mask.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that succeeds without clearing
// the previous 'target_cpa_micros' value cleanly.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });