ماسک های میدانی

در API گوگل ادز، از یک ماسک فیلد برای ارائه لیستی از فیلدهایی که یک درخواست API باید به‌روزرسانی کند، استفاده می‌شود. هر فیلدی که در ماسک فیلد مشخص نشده باشد، حتی اگر به سرور ارسال شود، نادیده گرفته خواهد شد.

کلاس FieldMaskUtil

روش پیشنهادی برای تولید ماسک‌های میدانی، استفاده از کلاس داخلی FieldMaskUtil است که به شما امکان می‌دهد ماسک‌های میدانی را از یک شیء اصلاح‌شده به جای ساخت آنها از ابتدا، تولید کنید.

در اینجا مثالی برای به‌روزرسانی یک کمپین آورده شده است که از متد 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 استفاده کند. این متد یک ماسک فیلد ایجاد می‌کند که تفاوت بین دو شیء را نشان می‌دهد.

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 سه زیرفیلد دارد، سرور Google Ads API انتظار دارد که ماسک‌های فیلد برای آن فیلدها در درخواست وجود داشته باشند. با این حال، FieldMaskUtil نمی‌تواند در این شرایط ماسک‌های فیلد را به درستی تولید کند، زیرا درخواست این فیلدها را تنظیم نمی‌کند.

در چنین مواردی، می‌توانید به صورت دستی ماسک فیلد را به صورت زیر ویرایش کنید:

// 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
};

نحوه پاک کردن فیلدها

API گوگل ادز از پاک کردن مقادیر برخی از فیلدها پشتیبانی می‌کند. برای پاک کردن یک فیلد، باید ماسک فیلد را به صورت دستی برای آن فیلد تنظیم کنید. تنظیم یک فیلد به مقدار پیش‌فرض آن (مانند صفر برای یک فیلد 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 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 });