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

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

برنامه FieldMasks

روش توصیه‌شده برای تولید پوشش‌های فیلد استفاده از ابزار داخلی پوشش فیلد ما (FieldMasks) است که به شما امکان می‌دهد پوشش‌های فیلد را از یک شیء اصلاح‌شده تولید کنید، به‌جای اینکه آن‌ها را از ابتدا بسازید.

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

use Google::Ads::GoogleAds::Utils::FieldMasks qw(all_set_fields_of field_mask);

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

my $campaign_operation =
  Google::Ads::GoogleAds::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

این مثال ابتدا با تنظیم نام منبع بااستفاده از ابزار ResourceNames، شیء Campaign را ایجاد می‌کند تا API بداند کدام پویش درحال به‌روزرسانی است.

این مثال از روش FieldMasks::all_set_fields_of() در کمپین استفاده می‌کند تا به‌طور خودکار ماسک فیلدی تولید کند که همه فیلدهای تنظیم‌شده را فهرست می‌کند. سپس می‌توانید پوشش برگشتی را مستقیماً به تماس به‌روزرسانی منتقل کنید.

‫FieldMasks::all_set_fields_of() روشی راحت برای FieldMasks::field_mask() است. شیء عبورکرده شما را با شیء خالی از همان کلاس مقایسه می‌کند. در کد قبلی، می‌توانید از این مورد نیز استفاده کنید:

field_mask(
  Google::Ads::GoogleAds::V26::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 می‌شود)، یا اصلاً زیرفیلد نداشته باشند (مثل ManualCpm).

فیلدهای شیء بدون فیلدهای فرعی تعریف‌شده

فیلد شیء در Perl معادل MESSAGE پروتکل بافر در کتابخانه‌های کارخواه درحال اجرا در 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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V26::Resources::MaximizeConversions
      ->new(),
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask includes 'maximize_conversions',
# which produces a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

# Sends the operation in a mutate request that results 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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
  });

# 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 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.
#
# See the guide on assigning standard and portfolio bidding strategies
# (/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::V26::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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V26::Resources::MaximizeConversions
      ->new({
        targetCpaMicros => 0,
      }),
  });

# Constructs an operation using all_set_fields_of to derive the update mask,
# which includes 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V26::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

توجه داشته باشید که فیلدهای دارای زیرفیلدهای تودرتو را فقط می‌توان با پاک کردن هریک از زیرفیلدهای جداگانه پاک کرد، همان‌طور که در فیلدهای شیء با زیرفیلدهای تعریف‌شده نشان داده شده است.