ماسک‌های فیلد

در Google Ads API، از ماسک فیلد برای ارائه فهرستی از فیلدها که درخواست 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 استفاده کنید. این روش ماسک فیلدی تولید می‌کند که تفاوت بین دو شیء را نشان می‌دهد:

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 تنظیم می‌کند. وقتی TargetCpaMicros برابر با 0 باشد یا وقتی مسیر از ماسک حذف شده باشد، هم ابزار کمکی FieldMasks و هم سرور Google Ads API این مقدار را نادیده می‌گیرند و سرور خطایی برنمی‌گرداند:

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