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