מבנה 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, שמבצעת חבילות של פעולות בכמה שירותים בלי לחכות להשלמתן. אחרי ששולחים משימה באצווה, שרתים של 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 זמין גם במאמרי העזרה של השדות.