Merchant API MCP Access Service (إصدار أوّلي)

استخدِم خدمة الوصول إلى Model Context Protocol (MCP) الخاصة بواجهة Merchant API للحصول على إذن بالوصول إلى بياناتك وإحصاءاتك في Merchant Center من أجل إنشاء تجارب جديدة مستندة إلى وكيل ومسارات عمل مؤتمتة.

نظرة عامة

توفّر خدمة الوصول إلى MCP في Merchant API جسرًا آمنًا وموحّدًا لنماذج اللغات الكبيرة والوكلاء ومساعدي الترميز من أجل إنشاء تجارب جديدة مستندة إلى الوكلاء وسير عمل مبرمَج يستند إلى بيانات Merchant Center وتنظيمه.

على وجه التحديد، يتيح هذا الإعداد الوصول المصرّح به إلى بياناتك في Merchant Center والتقارير والإحصاءات التي تنشئها Google لتنفيذ عمليات قراءة وكتابة محدودة فقط بهدف معالجة حالات الاستخدام التالية:

  • تشخيص حالات رفض المنتجات وحلّها
  • إنشاء تقارير وإحصاءات الأداء
  • مراجعة الموافقة على التحسينات التلقائية
  • إنشاء مصادر البيانات واسترجاعها

عناصر التحكّم في الأمان والوصول

تم تصميم خدمة الوصول إلى MCP في Merchant API مع إعطاء الأولوية للأمان:

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

اعتبارات مهمة

إنّ خدمة الوصول إلى MCP في Merchant API هي إصدار أولي، وسيتم توسيع نطاقها وإمكاناتها وقد تتغير.

قبل البدء، يُرجى مراجعة القيود وأفضل الممارسات التالية:

التغييرات والإصدارات

يمكن أن تحدث تغييرات بدون إشعار مسبق وسيتم نشرها في ملاحظات الإصدار.

الاختبار الآمن

ننصحك بتجربة هذه الأدوات أولاً باستخدام حساب تجريبي أو حساب غير نشط قبل استخدامها في بيئة التشغيل الفعلي.

الحصة المشترَكة

تتشارك خدمة الوصول إلى Merchant API MCP مجموعة الحصص نفسها مع طلبات Merchant API العادية. يمكن أن تستنفد البرامج الوكيلة التي تعمل باستمرار الحصة المخصّصة بسرعة، خاصةً بالنسبة إلى عمليات جلب مصادر البيانات. ننصحك بشدة باستخدام حساب تجريبي لمنع حدوث انقطاعات في الخدمة المباشرة.

فلترة الأدوات والأمان

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

ملخّص عن الإمكانات المتاحة

يمكنك استخدام خدمة الوصول إلى Merchant API MCP لتنفيذ الإجراءات التالية بطريقة آلية:

  • استرداد الحالة التفصيلية والسياق الخاص بالتقارير لمنتجات معيّنة باستخدام أسماء الموارد الدقيقة
  • إدراج منتجات متعدّدة والبحث عنها
  • مقاييس أداء طلبات البحث وحالات المنتجات وإحصاءات حول المنتجات الرائجة ومعلومات مفصّلة عن الأسعار ومعاينة أداء المنافسين وإحصاءات برنامج الشركاء التابعين في التسوّق على YouTube
  • تحديد المشاكل على مستوى الحساب التي تؤثّر في مستوى ظهور المنتجات أو المشاركة في البرنامج
  • إدراج مصادر البيانات وإنشاؤها واسترجاعها والتحقّق من حالة تحميلها
  • قائمة بالأسباب المجمّعة لرفض المنتجات في مستودعك
  • راجِع إعدادات التحسين التلقائي للعناصر والصور والشحن.
  • تحقَّق من المناطق النشطة والمتطلبات غير المستوفاة وحالة المشاركة في برامج معيّنة من Merchant Center.

الخطوات الأولى

لربط بيئة التطوير المتكاملة أو مساعد الترميز أو الوكيل بخدمة الوصول إلى بروتوكول Model Context Protocol (MCP) الخاص بواجهة Merchant API، عليك تعديل إعدادات عميل بروتوكول MCP. على سبيل المثال، يمكنك تعديل ملف mcp.json لـ Google Agent Studio أو Claude Desktop أو Antigravity أو Visual Studio Code أو إطار عمل الوكيل المخصّص.

يتطلّب إعداد خدمة الوصول إلى Merchant API MCP المحلية حساب خدمة. لا يتوفّر بروتوكول OAuth للمستخدم العادي في هذا التنفيذ المحلي بدون واجهة مستخدم رسومية. عليك إنشاء حساب خدمة وتنزيل ملف مفتاح JSON الخاص به وتوفير المسار المؤدي إليه مع معرّف Merchant Center المحدّد كمعلَمات.

للحصول على تعليمات مفصّلة حول كيفية إنشاء حساب خدمة وتنزيله، يُرجى الاطّلاع على دليل حسابات الخدمة.

إعداد بيانات العميل

عمليات إعداد الضبط:

Antigravity

اتّبِع التعليمات الواردة في مستندات Antigravity.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

‫Claude Desktop

اتّبِع التعليمات الواردة في مستندات Claude Desktop.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

أمثلة على سيناريوهات الاستخدام

لتوضيح كيفية الاستفادة من خدمة الوصول إلى بروتوكول MCP في Merchant API لإنشاء تجارب مستندة إلى وكيل ومسارات عمل مبرمَجة، إليك السيناريوهات التالية:

السيناريو 1: تشخيص حالات رفض المنتجات وحلّها

تريد معرفة سبب عدم ظهور منتج معيّن في نتائج البحث على Google.

طلب المستخدم:

"لماذا تم رفض منتجي الذي يحمل معرّف العرض الترويجي offer123؟"

سلوك الوكيل مع MCP:

  1. يستدعي الوكيل السمة list_products أو get_product_by_name لتحديد حالة المنتج.
  2. يعرض خادم MCP حالة المنتج، بما في ذلك قائمة issues (على سبيل المثال، "تنسيق السعر غير صحيح" أو "قيمة الشحن غير متوفّرة").
  3. يحلّل الوكيل المشاكل ويشرح لك السبب الأساسي لها، ويقترح عليك كيفية حلّها (على سبيل المثال، تعديل معلومات الأسعار).

السيناريو 2: مراجعة خيار تفعيل التحسينات التلقائية

تريد التأكّد ممّا إذا كانت ميزة "التحسينات التلقائية لمُدد الشحن" مفعّلة.

طلب المستخدم:

"هل ميزة التحسينات التلقائية لمُدد الشحن مفعّلة؟"

سلوك الوكيل مع MCP:

  1. يتصل الوكيل بـ get_automatic_improvements لاسترداد الإعدادات على مستوى الحساب.
  2. يعرض خادم MCP الإعدادات التي توضّح حالة التحسينات على الصور والمنتجات والشحن.
  3. يؤكّد الوكيل أنّ تحسينات الشحن مفعّلة، أو يوضّح كيفية تفعيلها إذا كانت غير مفعّلة.

السيناريو 3: إنشاء تقارير الأداء والإحصاءات

تريد الاطّلاع بسرعة على أدائك الأخير بدون التنقّل في واجهة مستخدم Merchant Center.

طلب المستخدم:

"عرض المنتجات الخمسة الأفضل أداءً حسب عدد النقرات في الأسبوع الماضي"

سلوك الوكيل مع MCP:

  1. ينشئ الوكيل طلب بحث بلغة الاستعلام في Merchant Center (MCQL) يستهدف الجدول product_performance_view، ويتم ترتيب النتائج حسب clicks DESC، ويتم حصرها على 5.
  2. يستدعي الوكيل report_search باستخدام طلب البحث الذي تم إنشاؤه.
  3. ينفّذ خادم MCP طلب البحث على قاعدة بيانات التقارير المباشرة ويعرض الصفوف.
  4. يُنسّق الوكيل النتائج في جدول Markdown منظَّم.

السيناريو 4: إنشاء مصادر بيانات واسترجاعها

تريد إضافة مصدر بيانات جديد لتحميل تعديلات المنتجات.

طلب المستخدم:

"أريد إنشاء مصدر بيانات تكميلي باسم price-updates لحساب التاجر الخاص بي".

سلوك الوكيل مع MCP:

  1. يطلب الوكيل create_data_source مع الإعدادات المحدّدة لتسجيل الخلاصة الجديدة.
  2. ينشئ خادم MCP مصدر البيانات ويعرض اسم المورد الفريد الخاص به.
  3. يستدعي الوكيل fetch_data_source لتفعيل عملية تنزيل الملف المرتبط ومعالجته.
  4. يتصل الوكيل get_file_upload لتتبُّع مستوى تقدّم عملية التحميل والتأكّد من حالة المعالجة الناجحة للعناصر.

أدوات MCP وأوصافها

تعرض خدمة Merchant API MCP Access Service الأدوات التالية للوكيل:

أداة MCP الوصف
get_product_by_name يمكنك الحصول على معلومات المنتج لبائع معيّن باستخدام اسم مصدر المنتج الدقيق. تعرض هذه الطريقة حالة المنتج المفصّلة التي تتضمّن سياق إعداد التقارير والمشاكل المحتملة على مستوى المنتج.
list_products عرض أو البحث عن منتجات متعدّدة لتاجر معيّن تعرض هذه السمة حالة المنتج المفصّلة التي تتضمّن سياق إعداد التقارير والمشاكل المحتملة على مستوى المنتجات لعدة منتجات.
report_search يمكنك طلب عرض جداول التقارير لاسترداد مقاييس أداء المنتجات وحالات المنتجات ومعلومات مفصّلة عن الأسعار ومعاينة أداء المنافسين. راجِع دليل التقارير للحصول على التفاصيل.
list_data_sources عرض قائمة بمصادر البيانات المتاحة لتاجر معيّن
get_data_source الحصول على تفاصيل مصدر بيانات معيّن
create_data_source إنشاء مصدر بيانات جديد لتاجر معيّن
fetch_data_source استرداد ومعالجة الملف المرتبط بمصدر بيانات لتاجر معيّن
get_file_upload الحصول على حالة آخر عملية تحميل ملف لمصدر بيانات معيّن
list_accounts تعرض هذه الطريقة قائمة بالحسابات الخاصة بمستخدم معيّن.
list_account_issues إدراج المشاكل على مستوى الحساب لتاجر معيّن من أجل تحديد المشاكل على مستوى الحساب
list_programs تعرض هذه الطريقة البرامج الخاصة بتاجر معيّن، بما في ذلك حالة المشاركة والمناطق النشطة وأي متطلبات لم يتم استيفاؤها.
list_aggregate_product_statuses يمكنك إدراج المشاكل المجمّعة على مستوى المنتجات لمراقبة الحالة العامة لبيانات منتجاتك.
get_automatic_improvements الحصول على إعدادات التحسينات التلقائية، بما في ذلك التعديلات على بيانات السلع وتحسينات الصور وتحسينات الشحن