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

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

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

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

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

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

לדוגמה, השיטה 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 או ב-mutating resources.

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

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

שגיאות בשינוי

כברירת מחדל (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