نظرة عامة

إليك Merchant API (الإصدار التجريبي)، البديل الرسمي لواجهة برمجة التطبيقات Content API for Shopping.

الاطّلاع على أحدث الميزات الجديدة وإصلاحات الأخطاء وتعديلات الإصدار من Merchant API (الإصدار التجريبي)

تعرَّف على كيفية إدارة نشاطك التجاري ومنتجاتك على Google وكيفية الحصول على إذن بالوصول الآلي إلى البيانات والإحصاءات والإمكانات الفريدة على نطاق واسع. ابدأ الآن

Reporting API

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

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

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

• المقاييس التي سيتم عرضها (على سبيل المثال: النقرات ومرّات الظهور)
• السمات التي سيتم تقسيم البيانات حسبها (على سبيل المثال: 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;

نموذج إجابة

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

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