אחרי שמגדירים את אפליקציית הלקוח כמו שמתואר באפליקציה הראשונה שלי, אפשר להשתמש ב-Search Ads 360 API כדי לבקש דוחות ולהוריד אותם. ניתן לשלוח כל אחד מסוגי הבקשות הבאים:
- סינכרוני
נדרשת רק בקשה אחת והחזרת הדוח בתגובה בפורמט JSON. בקשות סינכרוניות:
- ניתן להחזיר רק דוחות של מפרסם ושל חשבון מנוע חיפוש
- חסימת הלקוח עד שמערכת Search Ads 360 תיצור את הדוח
אם מבקשים דוחות גדולים של מפרסם או חשבון מנוע חיפוש, מומלץ להשתמש בגישה האסינכרונית.
- אסינכרוני
כדי להשתמש בדוח, צריך לשלוח בקשה ראשונית שבה יצוין הנתונים שרוצים שיופיעו בדוח. לאחר מכן, שולחים בקשות נוספות לסקר ב-Search Ads 360. כשיצירת הדוח תסתיים ב-Search Ads 360, יישלחו בקשות להורדת הדוח כקובץ אחד או יותר. בקשות אסינכרוניות:
- יכול להחזיר כל סוג דוח
- מפצל דוחות גדולים מאוד למספר קבצים
- עיצוב הדוחות כ-CSV או TSV
מודל נתונים: שורות ועמודות
מערכת Search Ads 360 מארגנת את הנתונים בדוח לפי שורות ועמודות. סוג הדוח שמבקשים קובע את השורות שיוחזרו. לדוגמה, אם הבקשה לדוח מילות מפתח, כל שורה תכיל נתונים על מילת מפתח אחת. במאמר בנושא סוגי דוחות מופיעה רשימה של כל סוגי הדוחות. כדי לציין אילו עמודות אתם רוצים שיופיעו בדוח, אתם יכולים לתת שם לכל עמודה בבקשת הדוח. במאמר סוגי דוחות מופיעה רשימה של העמודות שאפשר להחזיר לכל סוג דוח.
אופן הפעולה של העמודות
ההתנהגות של כל עמודה תלויה בסוג הנתונים שהעמודה מכילה (בהפניה לסוגי דוחות אפשר לראות את ההתנהגות של כל עמודה):
עמודות של מאפיינים. עמודת המאפיין מכילה נתונים שמגדירים או מזהים ישות בקמפיין, כמו שם הקמפיין או הצעת מחיר למילות מפתח. ה-Search Ads 360 API תמיד מחזיר את הערך הנוכחי של עמודת מאפיין, ללא קשר לתאריך או לטווח התאריכים שצוין בבקשה. לדוגמה, אם שינית אתמול הצעת מחיר של מילת מפתח מ-2.00 ל-1.50 ואז ביקשת דוח לנתונים של החודש שעבר, הדוח יחזיר ערך של 1.50 להצעת המחיר למילות מפתח.
עמודות של מדדים. עמודת מדד מכילה נתונים על ביצועי הקמפיין, למשל, מספר הקליקים על המודעה, מספר הביקורים שתועדו על ידי תג Floodlight או הכנסה. אם לא מציינים טווח זמן של יום אחד, ה-API מחזיר ערך מצטבר בעמודות של מדדים. לדוגמה, אם תבקשו דוח על הנתונים של החודש שעבר, ה-API יחזיר את מספר הקליקים הכולל מהחודש האחרון.
לפלח עמודות. עמודת פלח מפצלת את הנתונים לשורות נפרדות. לדוגמה,
dateהיא עמודת פלח שאפשר לציין בשביל סוגים רבים של דוחות. אם מציינים את העמודהdateבדוח של מילות מפתח עם טווח התאריכים 2013-01-01 עד 71-01-2013, ה-API יחזיר שבע שורות לכל מילת מפתח, שכל אחת מהן תואמת ליום אחד ומציגה מדדים לאותו יום. מידע נוסף זמין בקטע דוחות מפולחים.
סוגי מטבעות
בבקשת הדיווח יש לציין את המטבע של הנתונים הכספיים (שני מאפיינים כמו dailyBudget וגם מדדים כמו
cost). אפשר לציין אחת מהאפשרויות הבאות:
- המטבע של הסוכנות, אם הדוח מסווג לחשבון של סוכנות, מפרסם או מנוע חיפוש.
- המטבע של המפרסם, אם הדוח מוגבל לחשבון של מפרסם או לחשבון מנוע חיפוש.
- המטבע של חשבון מנוע החיפוש, אם הדוח מוגבל לחשבון מנוע חיפוש.
- USD
יש להשתמש במאפיין הבקשה Reports.request.statisticsCurrency
כדי לציין מטבע.
בדוח עצמו יצוין המטבע בנכס Reports.statisticsCurrencyCode.
אזור זמן
המדדים של Search Ads 360 נשמרים בתאריכים ללא אזורי זמן. התאריכים האלה תואמים לאזור הזמן
של חשבון מנוע החיפוש במדדי מנוע החיפוש (כמו קליקים, חשיפות וביקורים)
ואזור הזמן ברשת Campaign Manager למדדי המרות (כמו פעולות,
עסקאות והכנסות). כשכל מדד בדוח מגיע מאותו אזור זמן, אזור הזמן הזה יוחזר בבקשה. אחרת, לא יוחזר אזור זמן.
הבקשות שלכם יכולות לגרום ל-Reports.request.verifySingleTimeZone: true
להיכשל בדוחות שנכשלו עם מדדים מכמה אזורי זמן.
אם כל המדדים בדוח הם מאזור זמן אחד, אזור הזמן הזה
יוחזר ב-Reports.statisticsTimeZoneReports.