מבנה הקריאה ל-API

במדריך הזה מתואר המבנה הנפוץ של כל הקריאות ל-API.

אם אתם משתמשים בספריית לקוח כדי ליצור אינטראקציה עם ה-API, לא תצטרכו לדעת את פרטי הבקשה הבסיסיים. עם זאת, כדאי להכיר את המבנה של קריאות ה-API כדי לבצע בדיקות ולנפות באגים.

‫Google Ads API הוא gRPC API עם קשרי REST. כלומר, יש שתי דרכים לשלוח קריאות ל-API.

מועדף:

  1. יוצרים את גוף הבקשה כמאגר פרוטוקולים.

  2. שולחים אותו לשרת באמצעות HTTP/2.

  3. מבטלים את הסריאליזציה של התגובה ל-Protocol Buffer.

  4. פרש את התוצאות.

ברוב מסמכי התיעוד שלנו מוסבר על שימוש ב-gRPC.

אופציונלי:

  1. יוצרים את תוכן הבקשה כאובייקט JSON.

  2. שולחים אותו לשרת באמצעות HTTP 1.1.

  3. מבטלים את הסדר של התגובה כאובייקט JSON.

  4. פרש את התוצאות.

מידע נוסף על שימוש ב-REST זמין במדריך בנושא ממשק REST.

שמות המשאבים

רוב האובייקטים ב-API מזוהים באמצעות מחרוזות של שמות משאבים. המחרוזות האלה משמשות גם ככתובות URL כשמשתמשים בממשק REST. אפשר לראות את המבנה שלהם בשמות המשאבים של ממשק REST.

מזהים מורכבים

אם המזהה של אובייקט מסוים לא ייחודי באופן גלובלי, נוצר מזהה מורכב לאובייקט הזה על ידי הוספת המזהה של האובייקט ברמה שמעליו וסימן הטילדה (~) בתחילת המזהה.

לדוגמה, מזהה של מודעה בקבוצת מודעות הוא לא ייחודי באופן גלובלי, ולכן אנחנו מוסיפים לפניו את המזהה של אובייקט האב (קבוצת המודעות) כדי ליצור מזהה מורכב ייחודי:

  • ‫AdGroupId מתוך 123 + ~ + AdGroupAdId מתוך 45678 = מזהה מודעה משולבת של קבוצת מודעות 123~45678.

כותרות של בקשות

אלה כותרות ה-HTTP (או מטא-נתונים של grpc ‎) שמצורפות לגוף הבקשה:

אישור

צריך לכלול בטופס אסימון גישה של OAuth2 בתבנית Authorization: Bearer YOUR_ACCESS_TOKEN שמזהה חשבון ניהול שפועל בשם לקוח, או מפרסם שמנהל ישירות את החשבון שלו. הוראות לאחזור אסימון גישה מופיעות במדריך OAuth2. אסימון גישה תקף למשך שעה אחרי שקיבלתם אותו. כשפג התוקף שלו, צריך לרענן את אסימון הגישה כדי לקבל אסימון חדש. שימו לב: ספריות הלקוח שלנו מרעננות באופן אוטומטי טוקנים שתוקפם פג.

אם נתקלתם בשגיאות הרשאה, ודאו שאתם משתמשים בפרטי הכניסה הנכונים ושיש לכם הרשאות מספיקות. שגיאה USER_PERMISSION_DENIED מציינת שלמשתמש המאומת אין גישה לחשבון הלקוח שצוין בבקשה. פרטים על ניהול הרשאות זמינים במאמר בנושא רמות גישה ב-Google Ads.

developer-token

קוד מפתח הוא מחרוזת בת 22 תווים שמזהה באופן ייחודי מפתח של Google Ads API. דוגמה לנתוני קוד מפתח: ABcdeFGH93KL-NOPQ_STUv. אסימון המפתח צריך להיות בפורמט developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

זהו מספר הלקוח של הלקוח המורשה לשימוש בבקשה, ללא מקפים (-). אם הגישה שלכם לחשבון הלקוח היא דרך חשבון ניהול, הכותרת הזו נדרשת והיא צריכה להיות מוגדרת למספר הלקוח של חשבון הניהול. אם לא תכללו את login-customer-id כשאתם מבצעים אימות דרך חשבון ניהול, תופיע השגיאה AuthorizationError.USER_PERMISSION_DENIED. מידע נוסף על סוג השגיאה הזה זמין במאמר בנושא שגיאות נפוצות.

https://googleads.googleapis.com/v23/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 הוא מחרוזת שמזהה באופן ייחודי את הבקשה הזו.

הקודם
מטא-נתונים של משאבים