מבנה הקריאה ל-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) שמצורפות לגוף הבקשה:

אישור

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