Reporting API

ה-Reporting API מאפשר למוכרים לעבוד עם נתוני הביצועים שלהם באופן פרוגרמטי באמצעות Merchant Center Query Language (MCQL). האפשרות הזו דומה לאפשרות ליצור דוחות בהתאמה אישית ישירות ב-Merchant Center. היתרונות של Reporting API:

• מאפשר למוֹכרים גדולים לייבא נתוני ביצועים של כרטיסי מוצר אל מערכות הדיווח הפנימיות שלהם או אל מערכות דיווח של צד שלישי.
• מאפשר למשתמשים, לשותפים מצד שלישי ולאגרגטורים שמנהלים חשבונות Merchant Center לגשת לדוחות.

משתמשי API יכולים לציין אילו נתוני ביצועים הם רוצים לאחזר בתגובה לקריאה לחיפוש, למשל:

• המדדים שיוחזרו (לדוגמה: קליקים, חשיפות)
• מאפיינים שלפיהם יפולחו הנתונים (לדוגמה: OfferId, ‏ Date)
• התנאים שצריכים להתקיים (לדוגמה: קליקים > 100)

שפת השאילתות של Reporting API מאפשרת לשלוח שאילתות אל Content API for Shopping כדי לקבל מדדי ביצועים (קליקים, חשיפות), שאפשר לפלח אותם לפי מאפיינים שונים (מאפייני אירועים שדווחו כמו תוכנית ותאריך, ומאפייני מוצרים כמו מותג, קטגוריה וכו'), באמצעות method‏ Search בשירות Reports.

התוצאה של שאילתה לשירות Reports היא רשימה של מופעים של ReportRow, כאשר כל ReportRow מייצג את הערכים של המדדים המבוקשים עבור הפלחים שציינתם בשאילתה. אם לא מציינים פלחים, מוחזרת שורה אחת עם מדדים שמצטברים בכל הפלחים. אחרת, אם מתבקשים פלחים לצד מדדים, התשובה מציגה שורה אחת לכל טופל ייחודי של פלח. אפשר לבחור כמה פלחים וכמה מדדים בשאילתה אחת.

נקודה חשובה: אם אף פעם לא פרסמתם את המוצרים שלכם או שיתפתם אותם בכרטיסי מוצר חינמיים, לא יהיו לכם מדדים משויכים ותקבלו שדה תוצאות שמכיל מערך ריק.

שאילתה למדדים

אפשר להריץ שאילתות לגבי מדדים (קליקים, חשיפות, שיעור קליקים וכו') שרוצים לקבל לגביהם נתונים. כדי לשלוח שאילתה לשירות Reports, צריך להוסיף מסנן לטווח התאריכים. השאילתה לדוגמה שבהמשך מחזירה שורה אחת: הסכום המצטבר של הקליקים במסגרת התנאי הנוסף של טווח תאריכים.

SELECT metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-21';

נקודה חשובה: אתם צריכים לציין במפורש את הנתונים שאתם רוצים לקבל. תווים כלליים (לדוגמה, Select metrics.*) יחזירו שגיאה.

דוגמה לתשובה

תגובת קוד ה-JSON לדוגמה שמופיעה בהמשך מראה שלמוֹכֵר הזה היו 4,440 קליקים בסך הכול על כל המוצרים שלו בכל היעדים שלו בין 1 בדצמבר 2020 ל-21 בדצמבר 2020.

{"results": [
    {
      "metrics": {
        "clicks": "4,440"
      }
    }
]}

נקודה חשובה: אם לא בוחרים פלחים בשאילתה, המערכת תחזיר רק שורה אחת של מדדים.

שאילתה לפלחים

בנוסף למדדים, אפשר גם להריץ שאילתות לגבי פלחים, שיכולים להיות מאפיין של מוצר (offer_id, brand, category וכו') או מאפיין של אירוע שדווח (date, program). אירוע שדווח הוא חשיפה או קליק של מוצר.

פלחים פועלים באופן דומה ל-GROUP BY ב-SQL. הפלחים מפצלים את המדדים שנבחרו, ומקבצים לפי כל פלח בסעיף SELECT. השאילתה לדוגמה שבהמשך מחזירה את מספר הקליקים ליום, ממוינים לפי מספר הקליקים בסדר יורד במסגרת התנאי שנוסף של טווח תאריכים. יוחזרו רק שורות שבהן לפחות מדד מבוקש אחד הוא לא אפס.

SELECT
  segments.date,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-03'
ORDER BY metrics.clicks DESC;

דוגמה לתשובה

תגובת קוד ה-JSON לדוגמה שמופיעה בהמשך מראה שלמוכר הזה היו 1,546 קליקים על כל המוצרים שלו בכל היעדים שלו ב-1 בדצמבר 2020, ו-829 קליקים על כל המוצרים שלו בכל היעדים שלו ב-2 בדצמבר 2020. לא יוחזר אובייקט עבור 3 בדצמבר 2020, כי למוֹכר לא היו קליקים באותו יום.

{
  "results": [
    {
      "segments": {
        "date": {
          "year": 2020,
          "month": 12,
          "day": 1
        }
      },
      "metrics": {
        "clicks": "1546"
      }
    },
    {
      "segments": {
        "date": {
          "year": 2020,
          "month": 12,
          "day": 2
        }
      },
      "metrics": {
        "clicks": "829"
      }
    }
]}

נקודה חשובה: אפשר לבחור פלחים רק אם בוחרים גם מדדים. אם לא בוחרים מדדים בשאילתה, תוחזר שגיאה.