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

في 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 غير محدّد بأي حقول فرعية، استخدِم ملف برمجي 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" protocol buffers. ولكن بما أنّ target_cpa_micros ليس حقل optional، لا يعدّل الرمز "غير الصحيح" استراتيجية عروض الأسعار لتنظيف حقل target_cpa.

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