מבנה הקריאות ל-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 אחרי הכניסה או אחרי לחיצה על תמונת הפרופיל בפינה השמאלית העליונה. אם לא תכללו את הכותרת הזו, ברירת המחדל תהיה operating customer.

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

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