إشعارات باستخدام أقنعة الحقول

في Google Ads API، يتم إجراء التعديلات باستخدام قناع حقل. تعرض قائمة قناع الحقل جميع الحقول التي تريد تغييرها باستخدام التعديل، ويتم تجاهل أي حقول محددة غير مدرَجة في قناع الحقل، حتى إذا تم إرسالها إلى الخادم.

FieldMaskUtil

الطريقة المقترَحة لإنشاء أقنعة الحقول هي استخدام أداة قناع الحقل المضمّنة التي تخفي الكثير من التفاصيل المحدّدة وتتيح لك إنشاء أقنعة الحقول تلقائيًا من خلال تتبُّع التغييرات التي تجريها على حقول العنصر.

في ما يلي كيفية إنشاء قناع حقل لتعديل حملة:

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

ينشئ الرمز أولاً عنصر Campaign فارغًا، ثم يضبط اسم المورد الخاص به لإبلاغ واجهة برمجة التطبيقات بالحملة التي يتم تعديلها.

يستخدم هذا المثال طريقة client.field_mask.with في الحملة لبدء الحظر الذي يشمل التعديلات. في نهاية هذا القسم، تقارن الأداة المساعدة الحالة الحالية للحملة بعد القسم بالحالة الأولية للحملة قبل القسم، وتنشئ تلقائيًا قناع حقل يسرد الحقول التي تم تغييرها. يمكنك تقديم قناع الحقل هذا إلى العملية عند إنشائها لمكالمة التعديل على النحو التالي:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

يُنصح باستخدام هذه الطريقة عند إجراء عملية معقّدة والرغبة في التحكّم الدقيق في كل خطوة. ومع ذلك، يمكنك في معظم الحالات استخدام أداة مكتبة Ruby الأبسط:

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

تنشئ هذه الطريقة تلقائيًا مورد حملة فارغًا جديدًا، وتنشئ قناع الحقل استنادًا إلى التغييرات التي تجريها داخل الكتلة، وتنشئ عملية التعديل، وتعرض العملية النهائية مع ملء update وupdate_mask مسبقًا. يمكنك أيضًا تمرير حملة إلى الطريقة campaign لتحديد حالة بدء الحملة أيضًا. يعمل هذا النمط مع جميع الموارد التي تتيح عملية التعديل.

إنشاء قناع يدويًا

لإنشاء قناع حقل من البداية بدون استخدام أي أدوات مساعدة من المكتبة، عليك أولاً إنشاء Google::Protobuf::FieldMask، ثم إنشاء مصفوفة تتضمّن أسماء جميع الحقول التي تريد تغييرها، وأخيرًا تعيين المصفوفة إلى الحقل path الخاص بقناع الحقل.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

تعديل حقول الرسائل والحقول الفرعية

يمكن أن تتضمّن حقول MESSAGE حقولاً فرعية (مثل MaximizeConversions الذي يتضمّن ثلاثة حقول فرعية: target_cpa_micros وcpc_bid_ceiling_micros وcpc_bid_floor_micros)، أو يمكن ألا تتضمّن أي حقول فرعية (مثل ManualCpm).

حقول الرسائل التي لا تحتوي على حقول فرعية محددة

عند تعديل حقل MESSAGE غير محدّد بأي حقول فرعية، استخدِم FieldMaskUtil لإنشاء قناع حقل، كما هو موضّح سابقًا.

حقول الرسائل التي تتضمّن حقولاً فرعية محدّدة

عند تعديل حقل MESSAGE تم تحديده باستخدام حقول فرعية بدون ضبط أي من الحقول الفرعية هذه بشكل صريح في الرسالة، عليك إضافة كل حقل من الحقول الفرعية القابلة للتعديل MESSAGE إلى FieldMask يدويًا، على غرار المثال السابق الذي أنشأ قناع حقل من البداية.

أحد الأمثلة الشائعة هو تعديل استراتيجية عروض الأسعار لإحدى الحملات بدون ضبط أي من الحقول في استراتيجية عروض الأسعار الجديدة. يوضّح المثال التالي كيفية تعديل حملة لاستخدام استراتيجية عروض الأسعار MaximizeConversions بدون ضبط أي من الحقول الفرعية في استراتيجية عروض الأسعار.

في هذا المثال، لن يؤدي استخدام المقارنة المضمّنة في FieldMaskUtil إلى تحقيق الهدف المنشود.

تنشئ التعليمة البرمجية التالية قناع حقل يتضمّن maximize_conversions. ومع ذلك، لا تسمح واجهة برمجة التطبيقات Google Ads API بهذا السلوك من أجل منع محو الحقول عن طريق الخطأ، وتنتج الخطأ FieldMaskError.FIELD_HAS_SUBFIELDS.

تحذير: ينتج عن الرمز التالي خطأ.

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# 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.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

يوضّح الرمز التالي كيفية تعديل حملة بشكلٍ سليم لاستخدام استراتيجية عروض الأسعار MaximizeConversions بدون ضبط أي من الحقول الفرعية.

نجاح: يعمل الرمز البرمجي أدناه على تعديل استراتيجية عروض الأسعار للحملة بنجاح.

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

محو الحقول

يمكن محو بعض الحقول بشكل صريح. على غرار المثال السابق، يجب إضافة هذه الحقول بشكل صريح إلى قناع الحقل. على سبيل المثال، لنفترض أنّ لديك حملة تستخدم استراتيجية عروض أسعار MaximizeConversions وأنّه تم ضبط الحقل target_cpa_micros بقيمة أكبر من 0.

يتم تنفيذ الرمز التالي، ولكن لن تتم إضافة maximize_conversions.target_cpa_micros إلى قناع الحقل، وبالتالي لن يتم إجراء أي تغييرات على الحقل target_cpa_micros:

تحذير: يؤدي هذا الرمز إلى حدوث خطأ.

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

يوضّح الرمز البرمجي التالي كيفية محو الحقل target_cpa_micros بشكل صحيح في استراتيجية عروض الأسعار MaximizeConversions.

ناجح: الرمز التالي يمحو target_cpa_micros.

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

يُرجى العِلم أنّ الرمز "غير الصحيح" يعمل على النحو المنشود للحقول المحدّدة على أنّها optional في Google Ads API protocol buffers. ولكن بما أنّ target_cpa_micros ليس حقل optional، فإنّ الرمز "غير الصحيح" لا يعدّل استراتيجية عروض الأسعار لمحو الحقل target_cpa.

ملاحظة مهمة: إذا كنت تريد محو حقل، فإنّ الطريقة الأكثر أمانًا هي إضافة هذا الحقل بشكل صريح إلى قناع الحقل.