ماسک های میدانی

در Google Ads API، به روز رسانی ها با استفاده از یک فیلد ماسک انجام می شود. فیلد ماسک تمام فیلدهایی را که می‌خواهید با به‌روزرسانی تغییر دهید فهرست می‌کند و هر فیلد مشخص شده که در فیلد ماسک نیست نادیده گرفته می‌شود، حتی اگر به سرور ارسال شود. می‌توانید با ایجاد یک Google\Protobuf\FieldMask ، یک آرایه پر از نام تمام فیلدهایی که می‌خواهید تغییر دهید، و سپس آن را به فیلد مسیر فیلد ماسک اختصاص دهید، یک فیلد ماسک به صورت دستی ایجاد کنید.

همچنین می‌توانید از ابزار داخلی ماسک فیلد ( FieldMasks ) استفاده کنید که بسیاری از جزئیات خاص را پنهان می‌کند و به شما امکان می‌دهد با نظارت بر تغییراتی که در فیلدهای موجودیت ایجاد می‌کنید، ماسک‌های فیلد را به‌طور خودکار ایجاد کنید.

در اینجا یک مثال برای به روز رسانی یک کمپین آورده شده است:

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

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

این کد ابتدا یک شی Campaign ایجاد می کند و سپس نام منبع آن را با استفاده از ResourceNames تنظیم می کند تا API بداند کدام کمپین در حال به روز رسانی است. status نیز روی PAUSED تنظیم شده است.

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

توجه داشته باشید که FieldMasks::allSetFieldsOf یک روش مناسب برای FieldMasks::compare() است. شیء ارسال شده شما را با یک شی خالی از همان کلاس مقایسه می کند. به عنوان مثال، در کد قبلی، می‌توانید از FieldMasks::compare(new Campaign(), $campaign) به جای allSetFieldsOf() استفاده کنید.

به روز رسانی فیلدهای پیام و زیر فیلدهای آنها

فیلدهای 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 will include 'maximize_conversions`,
// which will produce 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 will result in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
// be included in a field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($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 all of the mutable
// fields (only one in this case) 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 will set 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 here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['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);

پاکسازی زمینه ها

برخی از فیلدها را می توان به صراحت پاک کرد. مشابه مثال قبلی، باید این فیلدها را به صراحت به فیلد ماسک اضافه کنید. برای مثال، فرض کنید کمپینی دارید که از استراتژی پیشنهاد قیمت 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' => 0]),
    'status' => CampaignStatus::PAUSED
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. However, the field mask will 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 will succeed but will 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($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 will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
$fieldMask = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['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);

توجه داشته باشید که کد "نادرست" برای فیلدهایی که در protocol buffers Google Ads API optional تعریف شده اند، همانطور که در نظر گرفته شده است، کار می کند. اما از آنجایی که target_cpa_micros یک فیلد optional نیست، کد "نادرست" استراتژی پیشنهاد قیمت را برای پاک کردن فیلد target_cpa به روز نمی کند.

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