מבנה הקריאה ל-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 (או metadata של 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

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

https://googleads.googleapis.com/v22/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 שאליו מועלים הנתונים (account A).
• הכותרות login-customer-id ו-Authorization: שילוב של ערכים לזיהוי משתמש שיש לו גישה לחשבון B.

כותרות תגובה

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

request-id

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