במדריך הזה מתואר המבנה המשותף של כל הקריאות ל-API.
אם אתם משתמשים בספריית לקוח כדי לקיים אינטראקציה עם ה-API, לא תוכלו צריך לדאוג לגבי פרטי הבקשה הבסיסיים. עם זאת, כדאי לדעת קצת עליהם כשבודקים ומאתרים באגים.
Google Ads API הוא gRPC API, עם קישורי REST. המשמעות היא שיש שתי דרכים לשלוח קריאות ל-API.
[מועדף] ליצור את גוף הבקשה בתור מאגר אחסון לפרוטוקולים, שולחים אותו לשרת באמצעות HTTP/2, פעולת deserialize של התשובה לפרוטוקול במאגר הנתונים הזמני ומפרשים את התוצאות. רוב התיעוד שלנו מתאר את השימוש gRPC.
[אופציונלי] יוצרים את גוף הבקשה בתור באובייקט 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.
אסימון הגישה תקף למשך שעה אחרי שמשיגים אותו. כשזה
בתוקף, צריך לרענן את אסימון הגישה כדי לאחזר אסימון חדש. חשוב לדעת שספריות הלקוח שלנו מרעננות באופן אוטומטי אסימונים שפג תוקפם.
developer-token
קוד מפתח הוא מחרוזת באורך 22 תווים שמזהה באופן ייחודי
מפתחי Google Ads API. דוגמה למחרוזת של קוד מפתח היא
ABcdeFGH93KL-NOPQ_STUv צריך לכלול את קוד המפתח
של developer-token : ABcdeFGH93KL-NOPQ_STUv.
login-customer-id
זהו מספר הלקוח של הלקוח המורשה להשתמש בו בבקשה.
ללא מקפים (-). אם הגישה לחשבון הלקוח היא דרך
חשבון ניהול, הכותרת הזו היא חובה וצריך להגדיר אותה כמספר הלקוח של
בחשבון הניהול.
https://googleads.googleapis.com/v17/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) מוחזרות עם גוף התגובה. מומלץ לרשום אותם למטרות ניפוי באגים.
request-id
השדה request-id הוא מחרוזת שמזהה באופן ייחודי את הבקשה הזו.