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

في 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

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

يستخدم هذا المثال طريقة 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.

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