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

ב-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

הקוד יוצר קודם אובייקט Campaign ריק, ואז מגדיר את שם המשאב שלו כדי להודיע ל-API על הקמפיין שמתעדכן.

בדוגמה הזו נעשה שימוש בשיטה client.field_mask.with בקמפיין כדי להתחיל את הבלוק שכולל את העדכונים. בסוף הבלוק הזה, הכלי משווה בין המצב הנוכחי של הקמפיין אחרי הבלוק לבין המצב הראשוני של הקמפיין לפני הבלוק, ויוצר באופן אוטומטי מסכת שדות שמפרטת את השדות שהשתנו. אפשר לספק את מסכת השדות הזו לפעולה כשיוצרים אותה לשיחה של ה-mutate באופן הבא:

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

יצירת מסכה באופן ידני

כדי ליצור מסכת שדה מאפס, בלי להשתמש בכלים של ספריות, צריך קודם ליצור 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

שימו לב שהקוד 'הלא נכון' פועל כמצופה בשדות שמוגדרים בתור optional ב-Google Ads API protocol buffers. עם זאת, מכיוון ש-target_cpa_micros הוא לא שדה optional, הקוד 'הלא נכון' לא מעדכן את שיטת הבידינג כדי לנקות את השדה target_cpa.

נקודת מפתח: אם אתם רוצים לנקות שדה, הדרך הבטוחה ביותר היא להוסיף את השדה הזה באופן מפורש למסכת השדה.