מבנה ה-API

ondemand_video סרטון: כדאי לצפות בהרצאה על שירותים ומשאבים מהסדנה לשנת 2019

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

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

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

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

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

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

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

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

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

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

משאבים

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

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

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

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

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

שמות המשאבים

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