أقنعة الحقل

في Google Ads API، يتم إجراء التعديلات باستخدام قناع حقل. يسرد قناع الحقل جميع الحقول التي تنوي تغييرها من خلال التعديل، ويتم تجاهل أي حقول محدّدة غير مضمّنة في قناع الحقل، حتى إذا تم إرسالها إلى الخادم. يمكنك إنشاء قناع حقل يدويًا من خلال إنشاء FieldMask (Google\Protobuf\FieldMask)، وإنشاء مصفوفة تتم تعبئتها بأسماء جميع الحقول التي تريد تغييرها، ثم تخصيص هذه المصفوفة لحقل paths في قناع الحقل.

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

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

$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'status' => CampaignStatusEnum\CampaignStatus::PAUSED
]);

$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

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

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

يُرجى العِلم أنّ FieldMasks::allSetFieldsOf() هي طريقة ملائمة لـ FieldMasks::compare(). فهي تقارن الكائن الذي تم تمريره بكائن فارغ من نفس الفئة. على سبيل المثال، في الرمز السابق، كان بإمكانك استخدام FieldMasks::compare(new Campaign(), $campaign) بدلاً من FieldMasks::allSetFieldsOf($campaign).

تعديل حقول الرسائل وحقولها الفرعية

يمكن أن تحتوي حقول MESSAGE على حقول فرعية (مثل MaximizeConversions، الذي يتضمّن حقولاً فرعية مثل target_cpa_micros وcpc_bid_ceiling_micros وcpc_bid_floor_micros)، أو يمكن ألا تحتوي على أي حقول فرعية (مثل ManualCpm).

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

عند تعديل حقل MESSAGE غير محدّد بأي حقول فرعية، استخدِم FieldMasks لإنشاء قناع حقل، كما هو موضّح سابقًا.

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

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

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

في هذه الحالة، لن يحقّق استخدام الطريقتَين allSetFieldsOf() وcompare() في FieldMasks الهدف المنشود.

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

تحذير: ينتج عن الرمز التالي خطأ.

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions()
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. The field mask includes 'maximize_conversions',
// which produces a FieldMaskError.FIELD_HAS_SUBFIELDS error.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// Sends the operation in a mutate request that results in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
// be included in a field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build($customerId, [$campaignOperation])
);

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

النجاح: يعمل الرمز التالي على تعديل استراتيجية عروض أسعار الحملة بنجاح.

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// Creates a field mask from the existing campaign and adds the mutable
// subfield on the MaximizeConversions bidding strategy to the field mask.
// Because this field is included in the field mask but excluded from the
// campaign object, the Google Ads API sets the campaign's bidding strategy
// to a MaximizeConversions object without any of its subfields set.
$fieldMask = FieldMasks::allSetFieldsOf($campaign);
// 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:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
$fieldMask->getPaths()[] = 'maximize_conversions.target_cpa_micros';

// Creates an operation to update the campaign with the specified fields.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

محو الحقول

يمكن محو بعض الحقول بشكل صريح. على غرار المثال السابق، عليك إضافة هذه الحقول بشكل صريح إلى قناع الحقل لأنّ FieldMasks يتجاهل حقول Proto3 العددية التي تم ضبطها على قيمها التلقائية (مثل 0 أو false أو ""). على سبيل المثال، لنفترض أنّ لديك حملة تستخدم استراتيجية عروض أسعار MaximizeConversions وأنّ الحقل target_cpa_micros تم ضبطه بقيمة أكبر من 0.

يتم تشغيل الرمز التالي، ولكن لن تتم إضافة maximize_conversions.target_cpa_micros إلى قناع الحقل، وبالتالي لن يتم إجراء أي تغييرات على حقل target_cpa_micros:

تحذير: لا ينتج عن هذا الرمز أي خطأ، ولكن لن يتم محو الحقل target_cpa_micros في استراتيجية عروض الأسعار MaximizeConversions.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions([
        'target_cpa_micros' => 0
    ]),
    'status' => CampaignStatusEnum\CampaignStatus::PAUSED
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. However, the field mask does NOT include
// 'maximize_conversions.target_cpa_micros'.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// Sends the operation in a mutate request that succeeds, but does NOT update
// the 'target_cpa_micros' field because
// 'maximize_conversions.target_cpa_micros' was not included in the field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build($customerId, [$campaignOperation])
);

يوضّح الرمز التالي كيفية محو حقل target_cpa_micros بشكل صحيح في استراتيجية عروض الأسعار MaximizeConversions.

النجاح: يمحو الرمز التالي الحقل target_cpa_micros.

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
$fieldMask = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->getPaths()[] = 'maximize_conversions.target_cpa_micros';

// Creates an operation to update the campaign with the specified field.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

يُرجى العِلم أنّ ضبط قيمة تلقائية يعمل على النحو المنشود للحقول التي يتم تحديدها على أنّها optional في مخازن بروتوكول Google Ads API. ومع ذلك، بما أنّ target_cpa_micros ليس حقلاً من النوع optional، فإنّ ضبطه على 0 بدون إضافة المسار صراحةً إلى قناع الحقل لا يؤدي إلى تعديل استراتيجية عروض الأسعار لمحو target_cpa_micros.

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