ضبط عناصر الرسائل الفارغة كحقول

في Google Ads API، تُستخدَم بعض حقول الرسائل للإشارة إلى اختيار استراتيجية عروض أسعار لـ Campaign. ويتّخذ هذا الأشكال التالية:

  • الرسائل الفارغة تمامًا: على سبيل المثال، campaign.manual_cpm ليس له أي حقول فرعية محدّدة.
  • الرسائل التي تحتوي على حقول اختيارية: على سبيل المثال، campaign.manual_cpc تحتوي على الحقل الفرعي الاختياري enhanced_cpc_enabled.

يُرجى العِلم أنّ حقول استراتيجية عروض الأسعار في Campaign تنتمي إلى مجموعة bidding_strategy oneof. يؤدي ضبط استراتيجية عروض أسعار جديدة، مثل manual_cpm أو manual_cpc، إلى محو أي استراتيجية عروض أسعار تم ضبطها سابقًا في مجموعة oneof هذه ضمنيًا.

لتعديل حقل أساسي، مثل campaign.name، يمكنك ضبطه مباشرةً:

campaign.name = "Test campaign value"

لتعديل رسالة متداخلة تحتوي على حقول فرعية قابلة للضبط، مثل campaign.manual_cpc عند تفعيل تكلفة النقرة المحسّنة، يمكنك ضبطها على النحو التالي:

campaign.manual_cpc.enhanced_cpc_enabled = True

ضبط الرسائل الفارغة تمامًا

لاستخدام استراتيجية عروض أسعار، مثل manual_cpm، وهي رسالة فارغة:

  1. احصل على نموذج فارغ من نوع الرسالة (ManualCpm).
  2. استخدِم client.copy_from لضبط هذا النموذج الفارغ في حقل الحملة.
  3. أضِف اسم الحقل (manual_cpm) يدويًا إلى update_mask في CampaignOperation. لا يمكن لأداة مساعد قناع الحقل رصد أنّه تم ضبط رسالة فارغة بشكلٍ صريح تلقائيًا.
from google.ads.googleads import util
from google.ads.googleads.client import GoogleAdsClient
from google.api_core.protobuf_helpers import field_mask

client = GoogleAdsClient.load_from_storage()
# Assume 'campaign' is an existing Campaign object you are updating.

# 1. Get an empty ManualCpm type.
empty_cpm = client.get_type("ManualCpm")

# 2. Copy it to the campaign's manual_cpm field.
client.copy_from(campaign.manual_cpm, empty_cpm)

# 3. Create the operation and manually add "manual_cpm" to the update_mask.
campaign_operation = client.get_type("CampaignOperation")
client.copy_from(campaign_operation.update, campaign)
client.copy_from(
    campaign_operation.update_mask,
    field_mask(None, util.convert_proto_plus_to_protobuf(campaign)),
)
campaign_operation.update_mask.paths.append("manual_cpm")

# The resulting proto sent to the API will include:
# manual_cpm {
# }

ضبط الرسائل التي تحتوي على حقول فرعية اختيارية

لاستخدام manual_cpc كاستراتيجية عروض أسعار بدون تفعيل enhanced_cpc_enabled، يمكنك تجربة طريقة مشابهة لـ ManualCpm. ومع ذلك، بما أنّ ManualCpc يحتوي على حقول فرعية، فإنّ إضافة manual_cpc إلى update_mask يؤدي إلى ظهور FieldMaskError.FIELD_HAS_SUBFIELDS خطأ. تتطلّب واجهة برمجة التطبيقات مزيدًا من التحديد عندما تحتوي رسالة في القناع على حقول فرعية.

لضبط campaign.manual_cpc بشكلٍ صحيح مع ضمان بقاء enhanced_cpc_enabled غير مضبوط:

  1. أنشئ كائن ManualCpc فارغًا وانسخه إلى campaign.manual_cpc باستخدام client.copy_from.
  2. أضِف يدويًا المسار إلى كل حقل فرعي قابل للتعديل في ManualCpc إلى الـ update_mask في الـ CampaignOperation. في هذه الحالة، يكون الحقل الفرعي ذو الصلة هو enhanced_cpc_enabled.
from google.ads.googleads import util
from google.ads.googleads.client import GoogleAdsClient
from google.api_core.protobuf_helpers import field_mask

client = GoogleAdsClient.load_from_storage()
# Assume 'campaign' is an existing Campaign object you are updating.

# 1. Copy an empty ManualCpc object into campaign.manual_cpc.
client.copy_from(campaign.manual_cpc, client.get_type("ManualCpc"))

# 2. Manually add the subfield path to the update_mask.
campaign_operation = client.get_type("CampaignOperation")
client.copy_from(campaign_operation.update, campaign)
client.copy_from(
    campaign_operation.update_mask,
    field_mask(None, util.convert_proto_plus_to_protobuf(campaign)),
)

# For ManualCpc, because it has subfields, you must specify the subfield
# path in the update_mask. This tells the API you are updating something
# within manual_cpc. By not setting enhanced_cpc_enabled on the campaign
# object, it defaults to false.
campaign_operation.update_mask.paths.append("manual_cpc.enhanced_cpc_enabled")

# The update_mask paths will include: ['manual_cpc.enhanced_cpc_enabled']
# This correctly signals to the API that ManualCpc is the chosen strategy,
# with enhanced_cpc_enabled in its default state.

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