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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لربط بيئة التطوير المتكاملة أو مساعد الترميز أو الوكيل بخدمة الوصول إلى MCP في Merchant API، عليك تعديل إعدادات عميل MCP. على سبيل المثال، عدِّل ملف mcp.json في Google Agent Studio أو Claude Desktop أو Antigravity أو Visual Studio Code أو إطار عمل الوكيل المخصّص.

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

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

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

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

Antigravity

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

{
    "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.

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

"اعرض لي أفضل 5 منتجات من حيث الأداء حسب عدد النقرات في الأسبوع الماضي."

سلوك الوكيل باستخدام 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 وأوصافها

تعرض خدمة الوصول إلى MCP في Merchant API الأدوات التالية لوكيلك:

أداة 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 الحصول على إعدادات التحسينات التلقائية، بما في ذلك تعديلات السلع وتحسينات الصور وتحسينات الشحن