סרטון: כדאי לצפות בהרצאה בנושא שירותים ומשאבים מהסדנה של 2019
במדריך הזה נסביר על הרכיבים העיקריים שמרכיבים את Google Ads API. Google Ads API מורכב ממשאבים ומשירותים. משאב מייצג ישות ב-Google Ads, בעוד ששירותים מאחזרים ישויות ב-Google Ads ומבצעים בהן פעולות.
היררכיית אובייקטים
אפשר להתייחס לחשבון Google Ads כאל היררכיה של אובייקטים.
המשאב ברמה העליונה של החשבון הוא הלקוח.
כל לקוח מכיל קמפיין פעיל אחד או יותר.
כל קמפיין מכיל קבוצת מודעות אחת או יותר, שמשמשות לקבץ את המודעות שלכם באוספים לוגיים.
מודעה בקבוצת מודעות מייצגת מודעה שאתם מציגים. כל קבוצת מודעות מכילה מודעה אחת לפחות, מלבד קמפיינים לקידום אפליקציות שבהם אפשר להוסיף רק מודעה אחת לכל קבוצת מודעות.
אפשר לצרף AdGroupCriterion או CampaignCriterion אחד או יותר לקבוצת מודעות או לקמפיין. הם מייצגים קריטריונים שמגדירים את אופן ההפעלה של המודעות.
יש הרבה סוגים של קריטריונים, כמו מילות מפתח, טווחי גיל ומיקומים. הקריטריונים שמוגדרים ברמת הקמפיין משפיעים על כל המשאבים האחרים בקמפיין. אפשר גם לציין תאריכים ותקציב ברמת הקמפיין.
לבסוף, אפשר לצרף תוספים ברמת החשבון, ברמת הקמפיין או ברמת קבוצת המודעות. תוספים מאפשרים לכם לספק מידע נוסף במודעות, כמו מספר טלפון, כתובת רחוב או מבצעים.
משאבים
המשאבים מייצגים את הישויות בחשבון Google Ads. Campaign ו-AdGroup הן שתי דוגמאות למשאבים.
מזהי אובייקטים
כל אובייקט ב-Google Ads מזוהה לפי מזהה משלו. חלק מהמזהים האלה הם ייחודיים בכל העולם בכל חשבונות Google Ads, וחלקם ייחודיים רק בהיקף מוגבל.
| מזהה האובייקט | היקף הייחודיות | ייחודית ברמת העולם? |
|---|---|---|
| מזהה תקציב | גלובלי | כן |
| מזהה קמפיין | גלובלי | כן |
| קוד זיהוי של קבוצת מודעות | גלובלי | כן |
| מזהה המודעה | קבוצת מודעות | לא, אבל הצמד (AdGroupId, AdId) הוא ייחודי ברמת המערכת |
| מזהה AdGroupCriterion | קבוצת מודעות | לא, אבל הצמד (AdGroupId, CriterionId) הוא ייחודי ברמת המערכת |
| CampaignCriterion ID | קמפיין | לא, אבל הצמד (CampaignId, CriterionId) הוא ייחודי ברמת המערכת |
| תוספים למודעות | קמפיין | לא, אבל הצמד (CampaignId, AdExtensionId) הוא ייחודי ברמת המערכת |
| מזהה העדכון | גלובלי | כן |
| מזהה הפריט בפיד | גלובלי | כן |
| מזהה מאפיין פיד | פיד | לא |
| מזהה מיפוי הפיד | גלובלי | כן |
| קוד זיהוי תווית | גלובלי | כן |
| מזהה רשימת משתמשים | גלובלי | כן |
כללי המזהים האלה יכולים להיות שימושיים בתכנון אחסון מקומי של אובייקטים ב-Google Ads.
אפשר להשתמש באובייקטים מסוימים בכמה סוגי ישויות. במקרים כאלה, האובייקט מכיל שדה type שמתאר את התוכן שלו. לדוגמה, הערך AdGroupAd יכול להתייחס לאובייקט כמו מודעת טקסט, מודעת מלון או מודעת עסק מקומי. אפשר לגשת לערך הזה דרך השדה AdGroupAd.ad.type, והוא מחזיר ערך במערך הערכים AdType.
שמות המשאבים
כל משאב מזוהה באופן ייחודי באמצעות מחרוזת resource_name, שמארגנת את המשאב ואת ההורים שלו לנתיב. לדוגמה, שמות המשאבים בקמפיין הם בפורמט:
customers/customer_id/campaigns/campaign_id
לכן, בקמפיין עם המזהה 987654 בחשבון Google Ads עם מספר הלקוח 1234567, הערך של resource_name יהיה:
customers/1234567/campaigns/987654
שירותים
שירותים מאפשרים לאחזר ולשנות את הישויות ב-Google Ads. יש שלושה סוגים של שירותים: שירותי שינוי, שירותי אחזור של אובייקטים ונתונים סטטיסטיים ושירותי אחזור של מטא-נתונים.
שינוי (מוטציה) של אובייקטים
השירותים האלה משנים את המופעים של סוג המשאב המשויך באמצעות בקשה מסוג mutate. הם מספקים גם בקשה מסוג get שמאחזרת מופע יחיד של משאב, שיכולה להיות שימושית לבדיקה של מבנה המשאב.
דוגמאות לשירותים:
CustomerServiceלשינוי לקוחות.CampaignServiceכדי לשנות קמפיינים.AdGroupServiceכדי לשנות קבוצות של מודעות.
כל בקשה של mutate חייבת לכלול אובייקטים תואמים של operation. לדוגמה, השיטה CampaignService.MutateCampaigns מצפה למופעים אחדים או יותר של CampaignOperation. במאמר שינוי ובדיקה של אובייקטים מפורטת סקירה של הפעולות.
שינויים בו-זמנית
לא ניתן לשנות אובייקט ב-Google Ads בו-זמנית על ידי יותר ממקור אחד. המצב הזה עלול לגרום לשגיאות אם יש כמה משתמשים שמעדכנים את אותו אובייקט באפליקציה, או אם מבצעים מוטציות של אובייקטים ב-Google Ads במקביל באמצעות כמה שרשורים. זה כולל עדכון של האובייקט מכמה שרשורים באותה אפליקציה, או מאפליקציות שונות (לדוגמה, האפליקציה שלכם וסשן בו-זמני בממשק המשתמש של Google Ads).
ב-API אין דרך לנעול אובייקט לפני העדכון. אם שני מקורות מנסים לבצע בו-זמנית שינוי (mutate) באובייקט, ה-API יוצר הודעת שגיאה מסוג DatabaseError.CONCURRENT_MODIFICATION_ERROR.
שינויים אסינכרונים לעומת שינויים סינכרוניים
השיטות של Google Ads API לשינוי נתונים הן סינכרוניות. קריאות ל-API מחזירות תשובה רק אחרי שהאובייקטים עוברים טרנספורמציה, כך שצריך להמתין לתגובה לכל בקשה. הגישה הזו פשוטה יחסית לתכנות, אבל היא עלולה להשפיע לרעה על איזון העומסים ולבזבז משאבים אם התהליכים נאלצים להמתין להשלמת הקריאות.
גישה חלופית היא לבצע מוטציות לאובייקטים באופן אסינכרוני באמצעות BatchJobService, שמבצע קבוצות של פעולות במספר שירותים בלי להמתין להשלמתן. אחרי ששולחים משימה באצווה, השרתים של Google Ads API מבצעים את הפעולות באופן אסינכררוני, ומאפשרים לתהליכים לבצע פעולות אחרות. אפשר לבדוק מדי פעם את סטטוס המשימה כדי לראות אם היא הושלמה.
מידע נוסף על עיבוד אסינכרוני זמין במדריך לעיבוד באצווה.
אימות של שינוי
אפשר לאמת את רוב הבקשות לשינוי נתונים בלי לבצע את הקריאה בפועל על נתונים אמיתיים. אפשר לבדוק את הבקשה כדי לאתר פרמטרים חסרים וערכים שגויים בשדות, בלי לבצע את הפעולה בפועל.
כדי להשתמש בתכונה הזו, צריך להגדיר את השדה הבווליאני האופציונלי validate_only בבקשה לערך true. לאחר מכן הבקשה תאומת באופן מלא כאילו היא עומדת להתבצע, אבל הביצוע הסופי יידלג. אם לא נמצאו שגיאות, תוחזר תשובה ריקה. אם האימות נכשל, הודעות השגיאה בתגובה יציינו את נקודות הכשל.
validate_only שימושי במיוחד לבדיקת מודעות כדי לזהות הפרות נפוצות של המדיניות. מודעות נדחות באופן אוטומטי אם הן מפירות את המדיניות, למשל אם הן מכילות מילים ספציפיות, סימני פיסוק, שימוש באותיות רישיות או אורך מסוים. מודעה אחת לא תקינה יכולה לגרום לכישלון של קבוצה שלמה. בדיקה של מודעה חדשה בתוך בקשת validate_only יכולה לחשוף הפרות כאלה. אפשר לעיין בדוגמה לקוד בנושא טיפול בשגיאות של הפרת מדיניות כדי לראות איך זה עובד.
אחזור נתונים סטטיסטיים על אובייקטים ועל ביצועים
GoogleAdsService הוא השירות המאוחד לאחזור אובייקטים ונתונים סטטיסטיים של ביצועים.
כל הבקשות מסוג Search ו-SearchStream ל-GoogleAdsService מחייבות שאילתות שמציינות את המשאב שאליו צריך לשלוח את השאילתה, את מאפייני המשאב ומדדי הביצועים שצריך לאחזר, את התנאים לשימוש בסינון הבקשה ואת הפלחים לשימוש בפירוט נוסף של נתוני הסטטיסטיקה של הביצועים. מידע נוסף על פורמט השאילתה זמין במדריך לשפת השאילתות של Google Ads.
אחזור מטא-נתונים
הפונקציה GoogleAdsFieldService מאחזרת מטא-נתונים על משאבים ב-Google Ads API, כמו המאפיינים הזמינים של משאב וסוג הנתונים שלו.
השירות הזה מספק מידע שנחוץ ליצירת שאילתה ל-GoogleAdsService. לנוחותכם, המידע שמוחזר על ידי GoogleAdsFieldService זמין גם במאמרי העזרה של השדות.