أقنعة الحقل

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

أداة FieldMasks

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

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

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

my $campaign_operation =
  Google::Ads::GoogleAds::V17::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::V17::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 لإنشاء قناع حقل، الموضحة أعلاه.

حقول العناصر التي تتضمن حقولاً فرعية محدّدة

عند تعديل حقل كائن معرّف بحقول فرعية بدون الإشارة بشكل صريح إعداد أي من الحقول الفرعية في هذه الرسالة، يجب إضافة كل حقول الكائن mutable الفرعية إلى 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::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V17::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::V17::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::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::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::V17::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::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V17::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::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

يُرجى العِلم أنّه لا يمكن محو الحقول التي تحتوي على حقول فرعية مدمَجة إلا من خلال محو كل الحقول الفرعية الفردية، كما هو موضح في حقول الكائنات ذات القيم المحددة الفرعية.