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

מזהי משאבים

הפנייה לאובייקטים ב-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.

כותרות של בקשות

אלה כותרות ה-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 בגרסה v25 ואילך (או AuthorizationError.ACTION_NOT_PERMITTED בגרסה v24 ואילך). פרטים על ניהול הרשאות זמינים במאמר בנושא רמות גישה ב-Google Ads.

login-customer-id

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

https://googleads.googleapis.com/v25/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 שנכשלו או לבקשות לא צפויות, צריך לספק את הערך הזה.

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