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

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

ابزار FieldMasks

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

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

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

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

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

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

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

field_mask(Google::Ads::GoogleAds::V16::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"]
  });

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

فیلدهای Object می توانند زیر فیلدهایی داشته باشند (مانند MaximizeConversions که دارای سه است: target_cpa_micros , cpc_bid_ceiling_micros و cpc_bid_floor_micros ). یا اصلاً نمی توانند هیچ کدام را نداشته باشند (مانند ManualCpm ).

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

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

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

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

# Creates a field mask from the existing campaign and adds all of the fields
# on the MaximizeConversions bidding strategy to the field mask. Because these
# fields are 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 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.
#
# Learn more about standard and portfolio bidding strategies here:
# https://developers.google.com/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::V16::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::V16::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V16::Resources::MaximizeConversions->new({
      targetCpaMicros => 0
    })
  });

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

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