סקירה כללית

Reporting API

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

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

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

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

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

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

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

שאילתת מדדים

אפשר להריץ שאילתות על מדדים (קליקים, חשיפות, שיעור קליקים וכו') שאתם רוצים שיוחזרו. צריך להוסיף מסנן לטווח התאריכים כדי להריץ שאילתות בשירות 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"
      }
    }
]}

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