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

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

ابزار FieldMasks

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

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

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

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

my $campaign_operation =
  Google::Ads::GoogleAds::V25::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::V25::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 ).

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

یک فیلد شیء در پرل معادل یک protobuf MESSAGE در کتابخانه‌های کلاینت در حال اجرا روی gRPC است. هنگام به‌روزرسانی یک فیلد شیء که با هیچ زیرفیلدی تعریف نشده است، از ابزار FieldMasks برای تولید یک ماسک فیلد، همانطور که در بخش قبل توضیح داده شد، استفاده کنید.

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

هنگام به‌روزرسانی یک فیلد شیء که با زیرفیلدها تعریف شده است، بدون تنظیم صریح هیچ یک از زیرفیلدهای آن پیام، باید هر یک از زیرفیلدهای شیء قابل تغییر را به صورت دستی به FieldMask اضافه کنید، مشابه مثال قبلی که یک ماسک فیلد را از ابتدا ایجاد می‌کند.

یک مثال رایج، به‌روزرسانی استراتژی پیشنهاد قیمت یک کمپین بدون تنظیم هیچ یک از فیلدهای استراتژی پیشنهاد قیمت جدید است. مثال زیر نحوه به‌روزرسانی یک کمپین برای استفاده از استراتژی پیشنهاد قیمت MaximizeConversions بدون تنظیم هیچ یک از زیرفیلدهای استراتژی پیشنهاد قیمت نشان می‌دهد.

در این حالت، استفاده از متدهای all_set_fields_of() و field_mask() از ابزار FieldMasks به هدف مورد نظر نمی‌رسد.

مثال زیر یک ماسک فیلد ایجاد می‌کند که شامل maximize_conversions می‌شود. با این حال، API گوگل ادز اجازه نمی‌دهد که این رفتار از پاک شدن تصادفی فیلدها جلوگیری کند و خطای FieldMaskError.FIELD_HAS_SUBFIELDS را ایجاد می‌کند.

هشدار: کد زیر خطا تولید می‌کند.

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign =
  Google::Ads::GoogleAds::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V25::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::V25::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::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::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::V25::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::V25::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V25::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::V25::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign),
  });

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