עדכונים באמצעות אנונימיזציה של שדות

ב-Google Ads API, העדכונים מתבצעים באמצעות מסכת שדות. מסכת השדות מפרטת את כל השדות שאתם מתכוונים לשנות באמצעות העדכון, וכל שדה שצוין ולא נמצא במסכת השדות לא יובא בחשבון, גם אם הוא נשלח לשרת.

כלי עזר לאנונימיזציה של שדות

הדרך המומלצת ליצור מסכות שדות היא באמצעות פונקציית העזר field_mask שכלולה בחבילה google.api_core. היא מקבלת שני אובייקטים של protobuf ומחזירה אובייקט של מסכת שדות עם רשימת paths שמכילה את כל השדות השונים בין שני האובייקטים.

אם מעבירים את None כפרמטר הראשון, רשימת מסכת השדות מכילה את כל השדות באובייקט השני של פרוטוקול באפר שלא מוגדרים לערך ברירת המחדל שלהם.

אחרי שיוצרים את אובייקט מסכת השדה, צריך להעתיק אותו לאובייקט הפעולה שיישלח לשרת.

עדכון מאובייקט מקומי חדש

בדוגמה הבאה, יוצרים אובייקט ריק 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)

עדכון של משאב קיים

בדוגמה הבאה מעדכנים קמפיין קיים שאוחזר מה-API, בהנחה ש-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. לפרטים נוספים, ראו הגדרת אובייקטים של הודעות ריקות כשדות.