מבנה הקריאות ל-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.

מזהי משאבים

הגישה לאובייקטים ב-Google Ads API מתבצעת באמצעות שמות משאבים מובְנים ומזהים מורכבים.

שמות המשאבים

רוב האובייקטים ב-API מזוהים לפי מחרוזות של שמות המשאבים שלהם. המחרוזות האלה משמשות גם ככתובות URL כשמשתמשים בממשק REST. המבנה שלהם מפורט בקטע שמות משאבים בממשק REST.

מזהים מורכבים

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

לדוגמה, ל-AdGroupAd יש את תבנית שם המשאב customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. המזהה המשולב של המודעה משלב את המזהה של קבוצת המודעות ברמה העליונה (ad_group.id) ואת המזהה של המודעה הבסיסית (ad_group_ad.ad.id). לכן, אנחנו מוסיפים את המזהה של קבוצת המודעות לפני המזהה של המודעה:

  • ‫AdGroupId מתוך 123 + ~ + AdId מתוך 45678 = מזהה מודעה של קבוצת מודעות משולבת של 123~45678.

Request headers

אלה כותרות ה-HTTP (או המטא-נתונים של gRPC) שמצורפות לגוף הבקשה:

אישור

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

אם נתקלתם בשגיאות הרשאה, ודאו שאתם משתמשים בפרטי הכניסה הנכונים ושיש לכם הרשאות מתאימות. השגיאה USER_PERMISSION_DENIED מציינת שיכול להיות שלמשתמש המאומת אין גישה לחשבון הלקוח שצוין בבקשה. אם הפרויקט שלכם ב-Google Cloud אושר רק לגישה לTest ואתם שולחים בקשה שמטרגטת חשבון בסביבת ייצור, ה-API מחזיר את השגיאה AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION בגרסה 25 ואילך (או AuthorizationError.ACTION_NOT_PERMITTED בגרסה 24 ומטה). במאמר רמות גישה ב-Google Ads מוסבר איך לנהל את ההרשאות.

login-customer-id

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

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

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

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