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

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

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

linked-customer-id

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

נניח ששותף צריך לבצע קריאות ל-API בחשבון Google Ads על סמך קישור למוצר.

  • מפרסם: חשבון Google Ads שמנוהל או מתעדכן על ידי קריאת ה-API. המזהה של חשבון המפרסם מצוין בבקשה. ב-REST, זהו פרמטר הנתיב customerId (לדוגמה, customers/1111111111/...), וב-gRPC, זהו השדה customer_id בבקשה.
  • שותף: החשבון של השותף (לדוגמה, ספק ניתוח נתונים של אפליקציות צד שלישי או שותף נתונים).
  • חשבון מקושר: חשבון Google Ads שיש לו קישור מוצרים לשותף, שמעניק לשותף גישה למפרסם.

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

כותרות הבקשה צריכות להיות מוגדרות באופן הבא:

  • ‫Authorization: אסימון OAuth2 למשתמש שיש לו גישה ל-Partner.
  • ‫developer-token: קוד המפתח של אפליקציית ה-API, בדרך כלל משויך לשותף.
  • ‫login-customer-id: מספר הלקוח של השותף. למשתמש המאומת צריכה להיות גישה לחשבון הזה.
  • ‫linked-customer-id: מספר הלקוח של החשבון המקושר. הכותרת הזו מציינת שההרשאה לבקשה הזו מסתמכת על קישור המוצר של החשבון המקושר עם השותף.

יש שני תרחישי קישור:

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

דוגמה 1: קישור ישיר

אם למפרסם 1111111111 יש קישור ישיר לשותף 2222222222, וקריאת ה-API מטרגטת אל customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

דוגמה 2: קישור לחשבון ניהול

אם חשבון מפרסם 1111111111 מנוהל על ידי חשבון ניהול 3333333333, לחשבון הניהול 3333333333 יש קישור לשותף 2222222222, והקריאה ל-API מטרגטת את customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

כותרות תגובה

הכותרות הבאות (או grpc trailing-metadata) מוחזרות עם גוף התגובה. מומלץ לרשום את הערכים האלה לצורך ניפוי באגים.

request-id

הערך request-id הוא מחרוזת שמזהה באופן ייחודי את הבקשה.

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