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

در Google Ads 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
};

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

Google Ads 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 });