במדריך הזה מוסבר המבנה המשותף של כל הקריאות ל-API.
אם אתם משתמשים בספריית לקוח כדי לקיים אינטראקציה עם ה-API, לא תצטרכו לדאוג לפרטים הבסיסיים של הבקשה. עם זאת, כדאי לדעת קצת עליהם כשבודקים ומאתרים באגים.
Google Ads API הוא API ל-gRPC עם קישורי REST. כלומר, יש שתי דרכים לבצע קריאות ל-API.
[האפשרות המועדפת] יוצרים את גוף הבקשה בתור מאגר פרוטוקול, שולחים אותו לשרת באמצעות HTTP/2, מבצעים דה-סריאליזציה של התגובה למאגר פרוטוקול ומפרשים את התוצאות. רוב המאמרים בתיעוד שלנו מתארים שימוש ב-gRPC.
[אופציונלי] יוצרים את גוף הבקשה כאובייקט JSON, שולחים אותו לשרת באמצעות HTTP 1.1, מבצעים דה-סריאליזציה של התגובה כאובייקט JSON ומפרשים את התוצאות. למידע נוסף על שימוש ב-REST, אפשר לעיין במדריך ממשק ה-REST.
שמות המשאבים
רוב האובייקטים ב-API מזוהים לפי מחרוזות השמות של המשאבים. המחרוזות האלה משמשות גם ככתובות URL כשמשתמשים בממשק ה-REST. המבנה שלהם מפורט במאמר שמות משאבים בממשק ה-REST.
מזהים מורכבים
אם המזהה של אובייקט לא ייחודי ברמה הגלובלית, המזהה המשולב של האובייקט נוצר על ידי הוספת המזהה של ההורה וקו נטוי (~) לתחילת המזהה.
לדוגמה, מאחר שמזהה מודעה של קבוצת מודעות לא ייחודי ברמת המערכת, אנחנו מוסיפים לו את מזהה האובייקט ההורה (קבוצת המודעות) כדי ליצור מזהה מורכב ייחודי:
AdGroupIdמ-123+~+AdGroupAdIdמ-45678= מזהה המודעה המורכב של קבוצת המודעות123~45678.
כותרות של בקשות
אלה כותרות ה-HTTP (או מטא-נתונים של grpc) שמתלוות לגוף הבקשה:
אישור
צריך לכלול אסימון גישה של OAuth2 בפורמט Authorization: Bearer YOUR_ACCESS_TOKEN שמזהה חשבון ניהול שפועל בשם לקוח או מפרסם שמנהל ישירות את החשבון שלו. הוראות לאחזור אסימון גישה מפורטות במדריך OAuth2. אסימון הגישה תקף למשך שעה אחת אחרי שמקבלים אותו. כשפג התוקף שלו, צריך לרענן את אסימון הגישה כדי לאחזר אסימון חדש. חשוב לדעת שספריות הלקוח שלנו מרעננות באופן אוטומטי אסימונים שפג תוקפם.
developer-token
אסימון מפתח הוא מחרוזת של 22 תווים שמזהה באופן ייחודי מפתח של Google Ads API. דוגמה למחרוזת של אסימון מפתח למפתחים היא ABcdeFGH93KL-NOPQ_STUv. אסימון המפתח צריך להופיע בפורמט developer-token : ABcdeFGH93KL-NOPQ_STUv.
login-customer-id
זהו מספר הלקוח המורשה שצריך להשתמש בו בבקשה, ללא מקפים (-). אם הגישה שלכם לחשבון הלקוח היא דרך חשבון ניהול, הכותרת הזו חובה וצריך להגדיר בה את מספר הלקוח של חשבון הניהול.
https://googleads.googleapis.com/v19/customers/1234567890/campaignBudgets:mutate
הגדרת השדה login-customer-id זהה לבחירת חשבון בממשק המשתמש של Google Ads אחרי הכניסה לחשבון או לחיצה על תמונת הפרופיל בפינה השמאלית העליונה. אם לא תכללו את הכותרת הזו, ברירת המחדל תהיה הלקוח המפעיל.
linked-customer-id
הכותרת הזו משמשת רק ספקים של שירותים לניתוח נתוני אפליקציות של צד שלישי כשהם מעלים המרות לחשבון Google Ads מקושר.
נניח שמשתמשים בחשבון A מעניקים לחשבון B הרשאת קריאה ועריכה של הישויות שלו דרך ThirdPartyAppAnalyticsLink.
אחרי הקישור, משתמש בחשבון B יכול לבצע קריאות API לחשבון A, בכפוף להרשאות שמספק הקישור. במקרה כזה, ההרשאות לקריאה ל-API בחשבון A נקבעות לפי הקישור של הצד השלישי לחשבון B, ולא לפי הקשר בין חשבון הניהול לחשבון הרלוונטי, שבו נעשה שימוש בקריאות אחרות ל-API.
ספק שירותי הניתוח של נתוני האפליקציות מצד שלישי מבצע קריאה ל-API באופן הבא:
linked-customer-id: החשבון של שירות הצד השלישי לניתוח נתוני האפליקציות שמעלה את הנתונים (חשבוןB).customer-id: חשבון Google Ads שאליו הנתונים מועלים (חשבוןA).- הכותרות
login-customer-idו-Authorization: שילוב של ערכים לזיהוי משתמש שיש לו גישה לחשבוןB.
כותרות תגובה
הכותרות הבאות (או grpc trailing-metadata) מוחזרות עם גוף התגובה. מומלץ לתעד את הערכים האלה ביומן למטרות ניפוי באגים.
request-id
השדה request-id הוא מחרוזת שמזהה באופן ייחודי את הבקשה הזו.