סקירה כללית

אנחנו רוצים להציג את גרסת הבטא של Merchant API. זאת הגרסה החדשה של ה-Content API, של העתיד.

Reporting API

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

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

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

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

שפת השאילתות של Reporting API יכולה לשלוח שאילתה ל-Content API for Shopping כדי להציג מדדי ביצועים (קליקים, חשיפות), ואולי גם מפולחים לפי מאפיינים שונים (מאפייני אירוע שדווחו, כמו תוכנית ותאריך ומאפייני מוצר כמו מותג, קטגוריה וכו'), באמצעות השיטה 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"
      }
    }
]}

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