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

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

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

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

  1. [Preferred] יוצרים את גוף הבקשה כמאגר אחסון לפרוטוקולים, שולחים אותו לשרת באמצעות HTTP/2, הופכים את התשובה למאגר נתונים זמני של פרוטוקול ומפרשים את התוצאות. ברוב המסמכים מוסבר על השימוש ב-gRPC.

  2. [Optional] יוצרים את גוף הבקשה כאובייקט JSON, שולחים אותו לשרת באמצעות HTTP 1.1, הופכים את התשובה כאובייקט JSON ומפרשים את התוצאות. מידע נוסף על השימוש ב-REST מופיע במדריך API ל-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/v17/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 הוא מחרוזת שמזהה את הבקשה הזו באופן ייחודי.

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