בדרך כלל קריאות ל-Search Ads 360 Reporting API מתבצעות דרך ספריית הלקוח שלכם. מידע נוסף זמין במאמר הסבר על ספריות לקוח. עם זאת, כדאי להכיר את המבנה של פרטי הבקשה הבסיסיים במהלך בדיקות וניפוי באגים.
Search Ads 360 Reporting API הוא gRPC API עם קישורי REST. המשמעות היא שאפשר לבצע קריאות ל-API בשתי דרכים חלופיות:
- השיטה המועדפת
- שימוש בספריית לקוח:
- יוצרים את גוף הבקשה כמאגר אחסון לפרוטוקולים.
- שולחים את הבקשה לשרת באמצעות HTTP/2.
- פעולת deserialize של התגובה למאגר של פרוטוקול.
- פרש את התוצאות.
- שיטה חלופית אופציונלית
- באמצעות REST:
- יוצרים את גוף הבקשה כאובייקט JSON.
- שולחים את הבקשה לשרת באמצעות HTTP 1.1.
- יש לבצע פעולת deserialize של התגובה כאובייקט JSON.
- פרש את התוצאות.
מידע נוסף זמין במאמר Google Cloud APIs.
הקטעים הבאים חלים על הפרוטוקולים gRPC ו-REST.
שמות המשאבים
רוב האובייקטים ב-API מזוהים באמצעות מחרוזות השמות של המשאבים שלהם. המחרוזות האלה משמשות גם ככתובות URL כשמשתמשים בממשק REST.
מידע נוסף על משאבים נתמכים ועל ייצוג הנתיבים שלהם זמין בהפניה > REST. אותו פורמט משמש גם בשירותים אחרים.
מזהים מרוכבים
אם המזהה של אובייקט לא ייחודי באופן גלובלי, המזהה המרוכב של האובייקט נוצר על ידי הוספת מזהה ההורה שלו וסימן טילדה (~).
לדוגמה, מכיוון שמזהה מודעה של קבוצת מודעות אינו ייחודי באופן גלובלי, מזהה אובייקט ההורה (קבוצת מודעות) מתווסף אליו בתחילת הערך. כתוצאה מכך, נוצר מזהה מורכב ייחודי.
דוגמה: AdGroupId של 123 + ~ + AdGroupAdId של 45678
= מזהה מודעה מורכב של קבוצת מודעות: 123~45678.
כותרות של בקשות
הכותרות של HTTP (או המטא-נתונים של gRPC) בקטעים הבאים צריכות להיכלל בגוף הבקשה.
הרשאות
עליך לכלול אסימון גישה מסוג OAuth2 בטופס:
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]
האסימון צריך לזהות חשבון ניהול שפועל מטעם לקוח או מפרסם שמנהל באופן ישיר את חשבון הניהול המשני או חשבון הלקוח שלו. מידע נוסף זמין במאמר מידע על חשבונות ניהול ב-Search Ads 360 ובמאמר אימות.
כותרת של מספר לקוח להתחברות
צריך להוסיף את הכותרת login-customer-id כשמשתמשים בחשבון ניהול כדי לגשת לחשבון ניהול משני או לחשבון לקוח. לא צריך לעשות זאת כשניגשים ישירות לחשבון ניהול משני או לחשבון לקוח. למרות שזה לא הכרחי לגמרי, אנחנו ממליצים לציין את התג login-customer-id למשתמשים מאומתים שיש להם גישה ליותר מחשבון אחד. כך אפשר למנוע עמימות ולמנוע הגדרה לא מכוונת של ההקשר לחשבון השגוי.
הבקשה צריכה לכלול את מספר הלקוח של המשתמש המורשה, ללא מקפים (-), לדוגמה:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets
הגדרת השדה login-customer-id מקבילה לבחירה בחשבון בממשק המשתמש של Search Ads 360 אחרי כניסה לחשבון או לחיצה על תמונת הפרופיל בפינה השמאלית העליונה.
כותרות תגובה
הכותרות הבאות (או gRPC Trailing-metadata) מוחזרות עם גוף התגובה. מומלץ לתעד את הערכים האלה למטרות ניפוי באגים.
מזהה בקשה
הכותרת request-id היא מחרוזת שמזהה את הבקשה באופן ייחודי.