به‌روزرسانی بااستفاده از پوشش‌های فیلد

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

راهنمای پوشش فیلد

روش توصیه‌شده برای تولید ماسک‌های فیلد استفاده از تابع کمکی field_mask است که در بسته google.api_core گنجانده شده است. این روش دو شیء protobuf را می‌پذیرد و یک شیء ماسک فیلد با فهرست paths برمی‌گرداند که شامل همه فیلدهایی است که بین دو شیء متفاوت هستند.

اگر None به‌عنوان پارامتر اول ارسال شود، فهرست ماسک فیلد حاوی همه فیلدهای موجود در شیء protobuf دوم است که روی مقدار پیش‌فرضشان تنظیم نشده‌اند.

پس‌از ساخت، شیء پوشش فیلد باید در شیء عملیات که به سرور ارسال خواهد شد کپی شود.

به‌روزرسانی از شیء محلی جدید

در مثال زیر، یک شیء CampaignOperation خالی ایجاد می‌کنید و یک شیء خالی Campaign را از فیلد update آن بازیابی می‌کنید. سپس آن شیء پویش را تغییر می‌دهید و با مقایسه آن با None، ماسک فیلد جدیدی می‌سازید که ماسک فیلدی حاوی فیلد network_settings.target_search_network تغییریافته را تولید می‌کند:

from google.ads.googleads.client import GoogleAdsClient
from google.api_core import protobuf_helpers

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()

# Create a new campaign operation.
campaign_operation = client.get_type("CampaignOperation")

# Retrieve a new campaign object from its update field and set its resource
# name.
campaign = campaign_operation.update
campaign.resource_name = client.get_service("CampaignService").campaign_path(
    customer_id, campaign_id
)

# Mutate the campaign (use direct attribute assignment in proto-plus).
campaign.network_settings.target_search_network = False

# Create a field mask using the updated campaign.
# The field_mask helper is compatible with raw protobuf message instances,
# which you can access using the ._pb attribute.
field_mask = protobuf_helpers.field_mask(None, campaign._pb)

# Copy the field_mask onto the operation's update_mask field.
client.copy_from(campaign_operation.update_mask, field_mask)

به‌روزرسانی منبع موجود

نمونه زیر پویش موجودی را که از میانای برنامه‌سازی کاربردی بازیابی شده است به‌روز می‌کند، با فرض اینکه resource_name و customer_id معتبر باشند. با این استراتژی، updated_campaign همه فیلدهای بازیابی‌شده در initial_campaign را هم‌رسانی می‌کند (ازجمله resource_name آن)، و ماسک فیلد تولیدشده به API می‌گوید که فقط فیلد network_settings.target_search_network تغییر کرده است:

from google.ads.googleads.client import GoogleAdsClient
from google.api_core import protobuf_helpers

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()

# Retrieve an instance of the GoogleAdsService.
googleads_service = client.get_service("GoogleAdsService")

# Search query to retrieve the campaign. Quote string literals in GAQL.
query = f"""
    SELECT
      campaign.network_settings.target_search_network,
      campaign.resource_name
    FROM campaign
    WHERE campaign.resource_name = '{resource_name}'"""

# Submit a query to retrieve a campaign instance.
response = googleads_service.search_stream(
    customer_id=customer_id, query=query
)

# Iterate over results to retrieve the campaign.
initial_campaign = None
for batch in response:
    for row in batch.results:
        initial_campaign = row.campaign
        break

if not initial_campaign:
    raise ValueError(f"Campaign '{resource_name}' not found.")

# Create a new campaign operation.
campaign_operation = client.get_type("CampaignOperation")

# Set the copied campaign object to a variable for easy reference.
updated_campaign = campaign_operation.update

# Copy the retrieved campaign into the new campaign.
# client.copy_from works with both native protobuf messages and messages
# wrapped by the proto-plus library.
client.copy_from(updated_campaign, initial_campaign)

# Mutate the new campaign.
updated_campaign.network_settings.target_search_network = False

# Create a field mask by comparing initial and updated protobuf objects.
field_mask = protobuf_helpers.field_mask(
    initial_campaign._pb, updated_campaign._pb
)

# Copy the field mask onto the operation's update_mask field.
# Note that the client's copy_from method works with both native messages
# and messages wrapped by proto-plus, including google.protobuf.field_mask_pb2.
client.copy_from(campaign_operation.update_mask, field_mask)

پاک کردن فیلدها یا تنظیم پیام‌های خالی

هنگام مقایسه با None، کمک‌کننده field_mask فیلدهای تنظیم‌شده روی مقادیر خالی یا پیش‌فرض را نادیده می‌گیرد. برای پاک کردن صریح فیلد یا تنظیم فیلد پیام خالی، مسیر فیلد را مستقیماً به campaign_operation.update_mask.paths اضافه کنید. برای جزئیات بیشتر، تنظیم کردن اشیای پیام خالی به‌عنوان فیلد را ببینید.