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

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

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

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

מועדף:

1. יוצרים את גוף הבקשה כמאגר אחסון לפרוטוקולים.
2. שולחים אותו לשרת באמצעות HTTP/2.
3. מבטלים את הסריאליזציה של התגובה ל-מאגר אחסון לפרוטוקולים.
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) שמצורפות לגוף הבקשה:

אישור

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

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

login-customer-id

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

https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/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 שיש לו קישור מוצרים עם השותף, שמעניק לשותף גישה למפרסם.

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

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

• ‫Authorization: אסימון גישה מסוג OAuth 2.0 למשתמש שיש לו גישה ל-Partner.
• ‫login-customer-id: מזהה הלקוח של השותף. למשתמש המאומת צריכה להיות גישה לחשבון הזה.
• ‫linked-customer-id: מזהה הלקוח של החשבון המקושר. הכותרת הזו מציינת שההרשאה לבקשה הזו מסתמכת על קישור מוצר של חשבון מקושר עם שותף.

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

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

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

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

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

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

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

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

כותרות תגובה

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

request-id

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