أقنعة الحقل

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

الأداة FieldMasks

إنّ الطريقة المقترَحة لإنشاء أقنعة الحقول هي استخدام أداة قناع الحقل المضمّنة (FieldMasks)، التي تتيح لك إنشاء أقنعة الحقول من عنصر معدَّل بدلاً من إنشائها من البداية.

في ما يلي مثال على تعديل حملة:

my $campaign = Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => PAUSED,
    networkSettings =>
      Google::Ads::GoogleAds::V19::Resources::NetworkSettings->new({
        targetSearchNetwork => "false"
      })
    });

my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

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

يستخدِم المثال الأسلوب FieldMasks::all_set_fields_of() في الحملة لإنشاء قناع حقل تلقائيًا يسرد جميع الحقول المحدّدة. يمكنك بعد ذلك تمرير القناع الذي تم إرجاعه مباشرةً إلى طلب التعديل.

‫FieldMasks::all_set_fields_of() هي طريقة مناسبة لتسجيل FieldMasks::field_mask(). تقارن هذه الطريقة بين العنصر الذي تم تمريره وعنصر فارغ من الفئة نفسها. وبالتالي، في الرمز أعلاه، يمكنك أيضًا استخدام

field_mask(Google::Ads::GoogleAds::V19::Resources::Campaign->new({}), $campaign)

بدلاً من all_set_fields_of($campaign).

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

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

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
    paths => ["status", "name"]
  });

تعديل حقول العناصر وحقولها الفرعية

يمكن أن تحتوي حقول العناصر على حقول فرعية (مثل MaximizeConversions التي تحتوي على ثلاثة حقول: target_cpa_micros وcpc_bid_ceiling_micros وcpc_bid_floor_micros)، أو يمكن ألا تحتوي على أي حقول فرعية على الإطلاق (مثل ManualCpm).

حقول الكائنات التي لا تحتوي على حقول فرعية محدّدة

حقل العنصر في Perl هو مكافئ لـ MESSAGE protobuf في مكتبات العميل التي تعمل على gRPC. عند تعديل حقل عنصر غير محدّد بأي حقول فرعية، استخدِم الأداة FieldMasks لإنشاء قناع حقل، كما هو описан أعلاه.

حقول الكائنات التي تحتوي على حقول فرعية محدّدة

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

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

في هذه الحالة، لا يؤدي استخدام الطريقتَين all_set_fields_of() وfield_mask() من المرافق FieldMasks إلى تحقيق الهدف المقصود.

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

تحذير: تؤدي التعليمة البرمجية التالية إلى ظهور خطأ.

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V19::Resources::MaximizeConversions->new()
    });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask will include 'maximize_conversions',
# which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
    customerId => $customer_id,
    operations => [$campaign_operation]
  });

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

النجاح: يُعدّ الرمز أدناه ناجحًا في تعديل استراتيجية عروض أسعار الحملة.

# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    )
  });

# Creates a field mask from the existing campaign and adds all of the fields
# on the MaximizeConversions bidding strategy to the field mask. Because these
# fields are included in the field mask but excluded from the campaign object,
# the Google Ads API will set the campaign's bidding strategy to a
# MaximizeConversions object with none of its subfields set.
# Only include 'maximize_conversions.target_cpa_micros' in the field mask
# as it is the only mutable subfield on MaximizeConversions when used as a
# standard bidding strategy.
#
# Learn more about standard and portfolio bidding strategies here:
# https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";

# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => $field_mask
  });

محو الحقول

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

النجاح: تعمل التعليمة البرمجية التالية على محو الحقل target_cpa_micros.

# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
  Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V19::Resources::MaximizeConversions->new({
      targetCpaMicros => 0
    })
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask, which will include 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

تجدر الإشارة إلى أنّه لا يمكن محو الحقول التي تحتوي على حقول فرعية مضمّنة إلا من خلال محو كل من الحقول الفرعية الفردية، كما هو موضّح في حقول العناصر التي تحتوي على حقول فرعية محدّدة.