بررسی اجمالی

گزارش API

Reporting API به تاجر اجازه می‌دهد تا با داده‌های عملکرد خود به‌صورت برنامه‌نویسی از طریق زبان پرس‌و‌جوی Merchant Center درگیر شود. این شبیه به توانایی ایجاد گزارش های سفارشی به طور مستقیم در Merchant Center است. گزارش API دارای مزایای زیر است:

• به تاجران بزرگ اجازه می‌دهد داده‌های عملکرد فهرست‌های محصولات را به سیستم‌های گزارش‌دهی داخلی یا شخص ثالث خود وارد کنند.
• به کاربران، شرکای شخص ثالث و جمع‌آورندگانی که حساب‌های Merchant Center را مدیریت می‌کنند، اجازه می‌دهد به گزارش دسترسی داشته باشند.

کاربران API می‌توانند مشخص کنند که کدام داده‌های عملکردی را می‌خواهند در پاسخ تماس جستجو بازیابی کنند، مانند:

• معیارهایی که باید برگردانده شوند (به عنوان مثال: کلیک‌ها، نمایش‌ها)
• ابعادی که در آن داده ها تقسیم می شوند (به عنوان مثال: OfferId، Date)
• شرایطی که باید رعایت شوند (به عنوان مثال: کلیک > 100)

زبان جستجوی Reporting API می‌تواند از Content API برای خرید برای معیارهای عملکرد (کلیک‌ها، نمایش‌ها) که احتمالاً بر اساس ابعاد مختلف (ویژگی‌های رویداد گزارش‌شده مانند برنامه و تاریخ، و ویژگی‌های محصول مانند نام تجاری، دسته و غیره) تقسیم‌بندی شده است، با استفاده از Search کند. روش در سرویس Reports

نتیجه یک پرس و جو به سرویس Reports فهرستی از نمونه های ReportRow است که هر ReportRow مقادیر معیارهای درخواستی برای بخش هایی را که در جستار خود مشخص کرده اید نشان می دهد. اگر هیچ بخش مشخص نشده باشد، یک ردیف با معیارهای جمع‌آوری شده در همه بخش‌ها برگردانده می‌شود. در غیر این صورت، اگر هر بخش در کنار معیارها درخواست شود، پاسخ یک ردیف را برای هر تاپل بخش منحصر به فرد نشان می دهد. انتخاب چندین بخش و چندین معیار در یک پرس و جو امکان پذیر است.

نکته کلیدی: اگر هرگز محصولات خود را تبلیغ نکرده اید یا آنها را در لیست های رایگان به اشتراک نگذاشته اید، هیچ معیار مرتبطی نخواهید داشت و یک فیلد نتایج حاوی یک آرایه خالی به شما بازگردانده می شود.

پرس و جو برای معیارها

می‌توانید معیارهایی (کلیک‌ها، تأثیرگذاری‌ها، CTR، و غیره) را که می‌خواهید برگردانید، جستجو کنید. برای پرس و جو از سرویس گزارش ها باید یک فیلتر در محدوده تاریخ اضافه کنید. پرس و جوی نمونه زیر یک ردیف را برمی گرداند: مقدار کل کلیک ها در شرایط اضافه شده یک محدوده تاریخ.

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

نکته کلیدی: باید در مورد داده هایی که می خواهید برگردانده شوند صریح باشید. هر علامت عام (مثلاً Select metrics.* ) یک خطا برمی‌گرداند.

نمونه پاسخ

نمونه پاسخ کد JSON در زیر نشان می‌دهد که چگونه این تاجر 4440 کلیک در همه محصولات خود در همه مقصدهای خود بین 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 در زیر نشان می‌دهد که چگونه این تاجر 1546 کلیک روی همه محصولاتش در همه مقصدهای خود در تاریخ 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"
      }
    }
]}

نکته کلیدی: بخش ها را تنها در صورتی می توان انتخاب کرد که معیارها نیز انتخاب شده باشند. اگر هیچ معیاری را در درخواست خود انتخاب نکنید، یک خطا به شما برگردانده می شود.