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

ב-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 שכולל 3: 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.

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