أقنعة الحقل

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