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

في 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 على الحملة لبدء الحظر الذي يشمل التعديلات. في نهاية هذه المجموعة، تقارن الأداة الحالة الحالية للحملة بعد الحظر بالحالة الأولية للحملة قبل الحظر، وتنشئ تلقائيًا قناعًا حقلاً يضمّ الحقول التي تم تغييرها. يمكنك توفير قناع الحقل هذا للعملية عند إنشائه لاستدعاء دالة mutate على النحو التالي:

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 لم يتم تحديده مع أي حقول فرعية، استخدِم FieldMaskUtill لإنشاء قناع حقل، كما هو موضَّح سابقًا.

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

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

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

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

ينشئ الرمز التالي قناع حقل يتضمن 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.

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