نظرة عامة

Reporting API

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

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

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

• المقاييس المطلوب عرضها (مثل النقرات ومرات الظهور)
• الأبعاد التي يتم استخدامها لتقسيم البيانات (مثل: رقم تعريف العرض والتاريخ)
• الشروط التي يجب استيفاؤها (مثل: النقرات > 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;

نموذج إجابة

يبيّن نموذج استجابة رمز 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"
      }
    }
]}

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