במדריך הזה מתואר המבנה המשותף של כל הקריאות ל-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 הוא מחרוזת שמזהה את הבקשה הזו באופן ייחודי.