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