שינוי אובייקטים

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

במדריך הזה נשתמש ב-CampaignService כדי להדגים שינוי של אובייקטים מסוג Campaign, אבל אותם מושגים חלים על כל שאר השירותים הספציפיים לסוגי המשאבים.

בקשות לשינוי נתונים

לכל שירות ספציפי לסוג משאב יש שיטת mutate שמקבלת בקשה לשינוי נתונים. הבקשה הזו כוללת:

• ‫customer_id (או customerId בכתובות URL של REST)
• אוסף של operations
• הגדרות הפעלה אופציונליות כמו partial_failure,‏ validate_only ו-response_content_type (שקובעת אם המשאב שניתן לשינוי או רק שם המשאב יוחזרו אחרי השינוי)

לדוגמה, ה-method‏ MutateCampaigns של CampaignService מקבלת MutateCampaignsRequest שמורכב מ:

• customer_id
• אוסף של CampaignOperation אובייקטים (operations)
• הגדרות הפעלה אופציונליות (partial_failure,‏ validate_only ו-response_content_type שמציינות את סוג התגובה המועדף)

תפעול

אובייקט של פעולה כמו CampaignOperation מאפשר לציין את הפעולה שרוצים לבצע במשאב יחיד, על ידי הגדרת השדה operation שלו. השדה הזה הוא שדה oneof שמורכב מהמאפיינים הבאים:

create

יוצרת מופע חדש של המשאב.

update

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

remove

הסרת המשאב שצוין במחרוזת של שם המשאב (לדוגמה, customers/1234567890/campaigns/987654321).

השדה operation הוא שדה oneof, ולכן אי אפשר להשתמש בפעולה אחת כדי לשנות כמה אובייקטים. לדוגמה, אם רוצים ליצור קמפיין אחד ולהסיר קמפיין אחר, מוסיפים לבקשה שני מופעים של CampaignOperation: אחד עם create והשני עם remove.

פעולות אצווה

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

לדוגמה, אם רוצים ליצור עשרה קמפיינים, צריך לשלוח MutateCampaignsRequest אחד שמכיל עשרה אובייקטים מסוג CampaignOperation. כדי לקבץ פעולות על סוגי משאבים שונים לבקשה אחת, משתמשים ב-GoogleAdsService.Mutate או במשאבים לשינוי.

תגובות לשינוי

התגובה שמוחזרת תלויה בערך שנשלח בשדה response_content_type של הבקשה לשינוי נתונים. לדוגמה, אם מציינים את MUTABLE_RESOURCE, התגובה מכילה גם את resource_name של המשאב וגם את השדות הניתנים לשינוי של הקמפיין ב-campaign. כברירת מחדל (RESOURCE_NAME_ONLY), רק השדה resource_name מאוכלס בכל MutateCampaignResult.

שגיאות בשינוי (mutate)

כברירת מחדל (partial_failure = false), הפעולות בבקשה לשינוי נתונים מיושמות בחשבון Google Ads רק אם כל הפעולות בבקשה בוצעו בהצלחה. אם אחת מהפעולות נכשלת, המערכת מבטלת את כל הבקשה. בבקשות לשינוי נתונים שתומכות בכשל חלקי (בקשות עם השדה partial_failure בהודעת הבקשה), הגדרת הערך partial_failure = true תגרום לכך שפעולות תקינות יבוצעו, ופעולות שנכשלו יחזירו שגיאות ספציפיות לפעולה בשדה partial_failure_error של התגובה. במדריך לטיפול בכשלים חלקיים ובמדריך לטיפול בשגיאות נפוצות מוסבר איך לטפל בשגיאות.

מעקב אחר שינויים

כדי לעקוב אחרי שינויים שבוצעו באובייקטים בחשבון Google Ads, או כדי לאחזר את המצב הנוכחי של האובייקטים, אתם יכולים להשתמש במשאבים change_status ו-change_event.

• change_status מספק סיכום של המשאבים שהשתנו בפרק זמן נתון.
• ‫change_event מספק היסטוריה מפורטת של השינויים, כולל הערכים הישנים והחדשים של השדות שהשתנו.

כדי לשלוח שאילתות למשאבים האלה, משתמשים ב-method‏ GoogleAdsService.SearchStream או ב-method‏ GoogleAdsService.Search. מידע נוסף על סטרימינג של דוחות באמצעות GoogleAdsService