نظرة عامة

نودّ إطلاعك على الإصدار التجريبي من Merchant API. إنه الإصدار الجديد من Content API والمستقبل.

Reporting API

تتيح Reporting API للتاجر التفاعل مع بيانات الأداء آليًا من خلال لغة طلب البحث في Merchant Center. وهذا يشبه إمكانية إنشاء تقارير مخصّصة مباشرةً في Merchant Center. توفّر Reporting API المزايا التالية:

• تسمح هذه الميزة للتجّار الكبار باستيراد بيانات الأداء الخاصة ببيانات المنتجات إلى أنظمة إعداد التقارير الداخلية أو التابعة لجهات خارجية.
• يتيح هذا الخيار للمستخدمين والشركاء الخارجيين ومجمّعي السلع الذين يديرون حسابات Merchant Center الوصول إلى التقارير.

يمكن لمستخدمي واجهة برمجة التطبيقات تحديد بيانات الأداء التي يريدون استردادها في الردّ على طلب "بحث Google"، مثل:

• المقاييس التي سيتم عرضها (على سبيل المثال: النقرات ومرات الظهور)
• السمات التي يتم تقسيم البيانات من خلالها (مثل: OfferId وDate)
• الشروط التي يجب استيفاؤها (مثل: عدد النقرات > 100)

يمكن أن ترسل لغة طلب البحث في Reporting API طلبات البحث في Content API for Shopping عن مقاييس الأداء (النقرات ومرّات الظهور)، ومن الممكن أن تكون مقسّمة حسب سمات مختلفة (سمات الأحداث المُبلغ عنها مثل البرنامج والتاريخ وسمات المنتج مثل العلامة التجارية والفئة وغير ذلك)، باستخدام طريقة Search في خدمة Reports.

النتيجة من طلب بحث إلى خدمة Reports هي قائمة بمثيلات ReportRow، ويمثّل كل ReportRow قيم المقاييس المطلوبة للأقسام التي حدّدتها في طلب البحث. إذا لم يتم تحديد أي شرائح، سيتم عرض صف واحد مع المقاييس المجمّعة على مستوى جميع الشرائح. وبخلاف ذلك، إذا تم طلب أي شرائح جنبًا إلى جنب مع المقاييس، فستعرض الإجابة صفًا واحدًا لكل صف شريحة فريدة. من الممكن تحديد شرائح متعددة ومقاييس متعددة في استعلام واحد.

نقطة رئيسية: إذا لم يسبق لك الإعلان عن منتجاتك أو مشاركتها في البيانات المجانية، لن تتوفّر لك أي مقاييس مرتبطة بها، وسيتم عرض حقل نتائج يحتوي على مصفوفة فارغة.

طلب بحث عن المقاييس

يمكنك طلب البحث عن المقاييس (النقرات ومرّات الظهور ونسبة النقر إلى الظهور وغيرها) التي تريد عرضها. يجب إضافة فلتر على النطاق الزمني للاستعلام عن خدمة "التقارير". يعرض نموذج طلب البحث أدناه صفًا واحدًا: العدد الإجمالي للنقرات خلال الشرط الإضافي للنطاق الزمني.

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;

نموذج إجابة

في 1 كانون الأول (ديسمبر) 2020، في نموذج الردّ على رمز JSON، تلقّى هذا التاجر 1,546 نقرة على جميع منتجاته في جميع وجهاته، و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"
      }
    }
]}

نقطة رئيسية: لا يمكن اختيار الشرائح إلا إذا تم تحديد المقاييس أيضًا. إذا لم تختَر أي مقاييس في طلب البحث، ستظهر لك رسالة خطأ.