در 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
به روز نمی کند.