به روز رسانی با استفاده از فیلد ماسک

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

FieldMaskUtil

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

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

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

کد ابتدا یک شی کمپین خالی ایجاد می کند، سپس نام منبع آن را تنظیم می کند تا API را از به روز رسانی کمپین مطلع کند.

این مثال از متد client.field_mask.with در کمپین برای شروع بلوکی که شامل به‌روزرسانی‌ها است، استفاده می‌کند. در پایان این بلوک، ابزار وضعیت فعلی کمپین پس از بلوک را با وضعیت اولیه کمپین قبل از بلوک مقایسه می‌کند و به طور خودکار یک فیلد ماسک با شمارش فیلدهای تغییر یافته تولید می‌کند. هنگام ساخت آن برای فراخوانی جهش، می توانید آن فیلد ماسک را به شرح زیر در اختیار عملیات قرار دهید:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

این روش زمانی توصیه می‌شود که در حال انجام یک عملیات پیچیده هستید و می‌خواهید کنترل خوبی روی هر مرحله داشته باشید. با این حال، برای بیشتر موارد، می‌توانید از ابزار ساده‌تر کتابخانه Ruby استفاده کنید:

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

این روش به طور خودکار یک منبع کمپین خالی جدید ایجاد می‌کند، ماسک فیلد را بر اساس تغییراتی که در بلوک ایجاد می‌کنید، می‌سازد، عملیات به‌روزرسانی را می‌سازد، و عملیات نهایی را با update و update_mask که قبلاً پر شده‌اند، برمی‌گرداند. همچنین می توانید یک کمپین را به روش campaign ارسال کنید تا وضعیت شروع کمپین را نیز مشخص کنید. این الگو برای همه منابعی که از عملیات به روز رسانی پشتیبانی می کنند کار می کند.

ایجاد یک ماسک به صورت دستی

برای ایجاد یک فیلد ماسک از ابتدا، بدون استفاده از ابزارهای کتابخانه ای، ابتدا یک Google::Protobuf::FieldMask ایجاد کنید، سپس یک آرایه با نام تمام فیلدهایی که می خواهید تغییر دهید ایجاد کنید و در نهایت آرایه را به آن اختصاص دهید. فیلد path ماسک میدان.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

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

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

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

هنگام به روز رسانی یک فیلد MESSAGE که با هیچ فیلد فرعی تعریف نشده است، از FieldMaskUtil برای ایجاد یک فیلد ماسک، همانطور که قبلا ارائه شد، استفاده کنید.

فیلدهای پیام با زیرفیلدهای تعریف شده

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

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

برای این مثال، استفاده از مقایسه داخلی FieldMaskUtil به هدف مورد نظر دست نمی یابد.

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

هشدار: کد زیر یک خطا ایجاد می کند.

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# 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.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

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

موفقیت: کد زیر استراتژی مناقصه کمپین را با موفقیت به روز می کند.

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

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

برخی از فیلدها را می توان به صراحت پاک کرد. مشابه مثال قبلی، باید این فیلدها را به صراحت به فیلد ماسک اضافه کنید. برای مثال، فرض کنید کمپینی دارید که از استراتژی پیشنهاد قیمت MaximizeConversions استفاده می کند و فیلد target_cpa_micros با مقداری بزرگتر از 0 تنظیم شده است.

کد زیر اجرا می شود؛ با این حال، maximize_conversions.target_cpa_micros به فیلد ماسک اضافه نخواهد شد و بنابراین هیچ تغییری در فیلد target_cpa_micros ایجاد نمی‌شود:

هشدار: این کد با خطا مواجه می شود.

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

کد زیر نحوه پاک کردن صحیح فیلد target_cpa_micros در استراتژی پیشنهادی MaximizeConversions را نشان می‌دهد.

موفقیت: کد زیر target_cpa_micros را پاک می کند.

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

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

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