מבנה ה-API

סרטון: כדאי לצפות בהרצאה על שירותים ומשאבים מהסדנה לשנת 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 עדיפות לא, אבל (CampaignId, CriterionId) הוא ייחודי בכל העולם
תוספים למודעות עדיפות לא, אבל (CampaignId, AdExtensionId) הוא ייחודי בכל העולם
מזהה הפיד עולמי כן
מזהה הפריט בפיד עולמי כן
מזהה מאפיין הפיד פיד לא
מזהה מיפוי פידים עולמי כן
קוד זיהוי תווית עולמי כן
מזהה של רשימת משתמשים עולמי כן

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

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

שמות המשאבים

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

customers/customer_id/campaigns/campaign_id

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

customers/1234567/campaigns/987654

שירותים

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

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

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

דוגמאות לשירותים:

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

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

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

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

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

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

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

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

הקודם
סקירה כללית
הבא
קשרי ישות