מבנה API

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

היררכיית האובייקטים

אפשר לראות חשבון Google Ads כהיררכיה של אובייקטים.

• המשאב ברמה העליונה של החשבון הוא customer.

• כל לקוח מכיל קמפיין פעיל אחד או יותר.

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

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

המבנה של קמפיינים למיקסום הביצועים שונה מזה של סוגי קמפיינים אחרים: במקום קבוצות של מודעות ומודעות בקבוצות של מודעות, קמפיין למיקסום הביצועים מכיל קבוצות נכסים. כדי לקשר נכסי קריאייטיב לקבוצת נכסים, משתמשים ב-AssetGroupAsset. כדי לצרף אותות של קהלים או נושאי חיפוש, משתמשים ב-AssetGroupSignal.

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

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

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

משאבים

משאבים מייצגים את הישויות בחשבון Google Ads. ‫Campaign ו-AdGroup הן שתי דוגמאות למשאבים.

מזהי אובייקטים

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

כללי המזהים האלה יכולים להיות שימושיים כשמתכננים אחסון מקומי לאובייקטים של Google Ads.

אפשר להשתמש באובייקטים מסוימים לכמה סוגי ישויות. במקרים כאלה, האובייקט מכיל שדה type שמתאר את התוכן שלו. לדוגמה, AdGroupAd יכול להתייחס לאובייקט כמו מודעה רספונסיבית לרשת החיפוש, מודעה להזמנת חדרים או מודעה ליצירת ביקוש. אפשר לגשת לערך הזה דרך השדה AdGroupAd.ad.type, והוא מחזיר ערך ב-enum‏ AdType. חשוב לדעת שהיכולת לשנות את הערך יכולה להשתנות בהתאם לגרסה (לדוגמה, אפשר לשנות את VideoResponsiveAdInfo ב-Ad בגרסה 24 ואילך).

שמות המשאבים

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

customers/customer_id/campaigns/campaign_id

לדוגמה, בקמפיין עם המזהה 987654 בחשבון Google Ads עם מספר הלקוח 1234567, הערך של resource_name יהיה:

customers/1234567/campaigns/987654

שירותים

השירותים מאפשרים לכם לאחזר ולשנות את הישויות שלכם ב-Google Ads. יש שלושה סוגים של שירותים: שירותי שינוי, שירותי אחזור של אובייקטים ונתונים סטטיסטיים ושירותי אחזור של מטא-נתונים.

שינוי (מוטציה) של אובייקטים

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

דוגמאות לשירותים ספציפיים למשאבים:

• ‫CustomerService לשינוי לקוחות.

• CampaignService לשינוי קמפיינים.

• AdGroupService כדי לשנות קבוצות של מודעות.

כל בקשה מסוג mutate חייבת לכלול אובייקטים תואמים מסוג operation. לדוגמה, ה-method‏ CampaignService.MutateCampaigns מצפה למופע אחד או יותר של CampaignOperation. לדיון מפורט על פעולות, ראו אובייקטים של שינויים.

שינויים בו-זמנית

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

ב-API אין אפשרות לנעול אובייקט לפני העדכון. אם שני מקורות מנסים לשנות אובייקט בו-זמנית, ה-API מעלה שגיאת DatabaseError.CONCURRENT_MODIFICATION_ERROR.

מוטציות אסינכרוניות לעומת מוטציות סינכרוניות

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

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

במדריך לעיבוד באצווה מוסבר בהרחבה על עיבוד אסינכרוני.

אימות שינוי נתונים

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

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

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

קבלת אובייקטים ונתונים סטטיסטיים של ביצועים

GoogleAdsService הוא השירות היחיד והמאוחד לאחזור אובייקטים ונתונים סטטיסטיים של ביצועים.

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

אחזור מטא-נתונים

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

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