שינוי ובדיקה של אובייקטים

מטרה: להבין איך לשנות ולבדוק אובייקטים באמצעות Google Ads API.

כמו שמתואר במדריך המבנה של API, לכל משאב ברמה העליונה ב-Google Ads API יש שירות תואם לסוג משאב ספציפי שתומך:

• שינוי מופעים של המשאב
• אחזור מופע אחד של המשאב לצורך בדיקה

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

מונח מפתח: משאב ברמה עליונה הוא משאב ששמו לא כולל נקודה (.). לדוגמה, Campaign הוא משאב ברמה העליונה, אבל Campaign.NetworkSettings לא.

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

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

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

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

• customerId
• אוסף של CampaignOperation אובייקטים
• השדה response_content_type שמציין את סוג התגובה המועדף.

פעולות

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

create

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

update

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

remove

המשאב יוסר.

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

פעולות אצווה

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

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

שינוי התשובות

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

שגיאות שינוי

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

אזהרה: התמיכה ב-get הופסקה. במקום זאת, משתמשים ב-search או ב-searchStream כדי לאחזר אובייקטים.

בדיקת אובייקטים באמצעות get (הוצא משימוש)

בנוסף לשינוי האובייקטים, לכל שירות שספציפי לסוג משאב יש גם שיטת get לאחזור כל המאפיינים של משאב יחיד. ה-method הזה מקבל בקשת get שהמאפיין היחיד שלה הוא resource_name.

נקודה חשובה: השתמשו ב-get בצורה מצומצמת.

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