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

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

FieldMaskUtil

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

در اینجا یک مثال برای به روز رسانی یک کمپین آورده شده است:

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

ابتدا یک شئ Campaign خالی می سازیم. سپس، نام منبع آن را طوری تنظیم می کنیم که API دقیقاً بداند کدام کمپین را به روز می کنیم.

در این مثال از روش FieldMasks.AllSetFieldsOf در کمپین استفاده می شود که به طور خودکار یک فیلد ماسک تولید می کند که تمام فیلدهای مجموعه را شمارش می کند. سپس می توانید ماسک برگشتی را مستقیماً به تماس به روز رسانی منتقل کنید.

گاهی اوقات، ممکن است لازم باشد با یک شی موجود کار کنید و چند فیلد را به روز کنید. در چنین مواردی، کد را به صورت زیر تغییر می دهید:

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

برای ایجاد یک فیلد ماسک از ابتدا، ابتدا یک شی FieldMask ایجاد می‌کنید، سپس یک آرایه با نام تمام فیلدهایی که می‌خواهید تغییر دهید ایجاد می‌کنید و در نهایت محتوای آرایه را به فیلد Path فیلد ماسک اضافه می‌کنید.

FieldMask fieldMask = new FieldMask();
fieldMask.Paths.AddRange(new string[] { "status", "name" });

به روز رسانی فیلدهای پیام و زیر فیلدهای آنها

فیلدهای MESSAGE می‌توانند زیرفیلدهایی داشته باشند (مانند MaximizeConversions که دارای سه فیلد است: target_cpa_micros ، cpc_bid_ceiling_micros و cpc_bid_floor_micros )، یا اصلاً نمی‌توانند هیچ کدام را نداشته باشند (مانند ManualCpm ).

فیلدهای پیام بدون زیرفیلدهای تعریف شده

هنگام به روز رسانی یک فیلد MESSAGE که با هیچ زیر فیلد تعریف نشده است، از FieldMasks برای ایجاد یک فیلد ماسک، همانطور که در بالا توضیح داده شد، استفاده کنید.

فیلدهای پیام با زیرفیلدهای تعریف شده

هنگام به روز رسانی یک فیلد MESSAGE که با فیلدهای فرعی بدون تنظیم صریح هیچ یک از فیلدهای فرعی در آن پیام تعریف شده است، باید به صورت دستی هر یک از زیرفیلدهای MESSAGE قابل تغییر را به FieldMask اضافه کنید، مشابه مثال بالا که یک فیلد ماسک از ابتدا ایجاد می کند.

یکی از مثال‌های رایج، به‌روزرسانی استراتژی مناقصه یک کمپین بدون تنظیم هیچ یک از فیلدها در استراتژی مناقصه جدید است. مثال زیر نحوه به‌روزرسانی یک کمپین را برای استفاده از استراتژی پیشنهادی MaximizeConversions بدون تنظیم هیچ یک از زیرفیلدهای استراتژی پیشنهاد می‌دهد.

در این حالت استفاده از متدهای AllSetFieldsOf() و FromChanges() FieldMasks به هدف مورد نظر دست نمی یابد.

مثال زیر یک فیلد ماسک ایجاد می کند که شامل maximize_conversions است. با این حال، API Google Ads اجازه نمی دهد که این رفتار از پاک کردن تصادفی فیلدها جلوگیری کند و یک خطای 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()
};

// Constructs an operation, using the FieldMasks' AllSetFieldsOf utility to
// derive the update mask. The field mask will include 'maximize_conversions`,
// which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that will result in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
// be included in a field mask.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

مثال زیر نحوه به روز رسانی صحیح یک کمپین برای استفاده از استراتژی پیشنهاد قیمت MaximizeConversions بدون تنظیم هیچ یک از زیرفیلدهای آن نشان می دهد.

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

// Creates a field mask from the existing campaign and adds all of the fields
// on the MaximizeConversions bidding strategy to the field mask. Because these
// fields are included in the field mask but excluded from the campaign object,
// the Google Ads API will set the campaign's bidding strategy to a
// MaximizeConversions object with none of its subfields set.
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
};

پاکسازی فیلدها

برخی از فیلدها را می توان به صراحت پاک کرد. مشابه مثال بالا، شما باید به صراحت این فیلدها را به فیلد ماسک اضافه کنید. به عنوان مثال، فرض کنید کمپینی دارید که از استراتژی پیشنهاد قیمت MaximizeConversions استفاده می کند و فیلد target_cpa_micros با مقداری بزرگتر از 0 تنظیم شده است.

کد زیر اجرا می شود؛ با این حال، maximize_conversions.target_cpa_micros به فیلد ماسک اضافه نخواهد شد و بنابراین هیچ تغییری در فیلد target_cpa_micros ایجاد نمی‌شود:

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set 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 });

مثال بعدی نحوه پاکسازی صحیح فیلد target_cpa_micros در استراتژی پیشنهادی MaximizeConversions را نشان می‌دهد.

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

توجه داشته باشید که مثال "نادرست" بالا برای فیلدهایی که به عنوان optional در protocol buffers Google Ads API تعریف شده اند، همانطور که در نظر گرفته شده است، کار می کند. اما از آنجایی که target_cpa_micros یک فیلد optional نیست، مثال "نادرست" استراتژی مناقصه را برای پاک کردن فیلد target_cpa به روز نمی کند.