ماسک‌های فیلد

در 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 تنظیم می‌کند تا API بداند کدام پویش درحال به‌روزرسانی است. ‫status نیز روی CampaignStatus::PAUSED تنظیم شده است.

سپس کد یک شیء CampaignOperation ایجاد می‌کند و پویشی را که قبلاً ایجاد شده است روی آن تنظیم می‌کند. پس‌از آن، از FieldMasks::allSetFieldsOf() برای ایجاد ماسک فیلد برای پویش با شمارش همه فیلدهای اصلاح‌شده استفاده می‌کند. درنهایت، ماسک برگردانده‌شده را به شیء عملیات پویش ارسال می‌کند.

توجه داشته باشید که FieldMasks::allSetFieldsOf() روشی راحت برای FieldMasks::compare() است. این روش شیء ارسال‌شده شما را با شیء خالی از همان کلاس مقایسه می‌کند. برای مثال، در کد قبلی، می‌توانستید به‌جای FieldMasks::allSetFieldsOf($campaign) از FieldMasks::compare(new Campaign(), $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 به‌روز نمی‌کند.

نکته کلیدی: اگر قصدتان پاک کردن فیلدی است، ایمن‌ترین راه این است که آن فیلد را صریحاً به ماسک فیلد اضافه کنید.