בדרך כלל, קריאות ל-Search Ads 360 Reporting API מתבצעות דרך ספריית הלקוח. מידע נוסף זמין במאמר הסבר על ספריות לקוח. עם זאת, מומלץ להכיר את המבנה של פרטי הבקשה הבסיסית כדי לבצע בדיקות ולפתור באגים.
Search Ads 360 Reporting API הוא gRPC API עם קישורי REST. כלומר, אפשר לבצע קריאות ל-API בשתי דרכים חלופיות:
- השיטה המועדפת
- שימוש בספריית לקוח:
- יוצרים את גוף הבקשה כמאגר פרוטוקול.
- שולחים את הבקשה לשרת באמצעות HTTP/2.
- ביצוע דה-סריאליזציה של התגובה למאגר פרוטוקול.
- פרש את התוצאות.
- שיטה חלופית אופציונלית
- שימוש ב-REST:
- יוצרים את גוף הבקשה כאובייקט JSON.
- שולחים את הבקשה לשרת באמצעות HTTP 1.1.
- מבצעים דה-סריאליזציה של התגובה כאובייקט JSON.
- פרש את התוצאות.
מידע נוסף זמין במאמר ממשקי API של Google Cloud.
הקטעים הבאים חלים גם על פרוטוקול 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) מוחזרות עם גוף התגובה. מומלץ לתעד את הערכים האלה ביומן למטרות ניפוי באגים.
מזהה בקשה
הכותרת request-id היא מחרוזת שמזהה את הבקשה באופן ייחודי.