أقنعة الحقل

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

أداة FieldMasks

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

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

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

my $campaign_operation =
  Google::Ads::GoogleAds::V21::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::V21::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 في بروتوكول buffer في مكتبات البرامج التي تعمل على 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::V21::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V21::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::V21::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::V21::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V21::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::V21::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::V21::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V21::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::V21::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

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