أقنعة الحقل

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

يتعذّر تنفيذ طلب البيانات هذا من واجهة برمجة التطبيقات بسبب الخطأ 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. تتجاهل كل من الأداة المساعدة FieldMasks وخادم Google Ads API هذه القيمة عندما يكون TargetCpaMicros هو 0 أو عندما يتم حذف المسار من القناع، ولا يعرض الخادم خطأ:

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