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