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

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

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