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 أو حساب الخدمة. ننصح باستخدام بيانات اعتماد تتضمّن حقوق الوصول الأكثر تقييدًا الممكنة.
  • أمان التنفيذ: على الرغم من أنّ مستوى ظهور الأداة غير مقيّد للاكتشاف المستند إلى الوكلاء ، فإنّ تنفيذ الأداة يقتصر على بيانات اعتماد واجهة برمجة التطبيقات المحدّدة.
  • إجراءات الوق101اية: تقتصر الأدوات بشكلٍ صارم على عمليات القراءة فقط وأدوات الكتابة منخفضة المخاطر (مثل إنشاء مصدر بيانات) كإجراء وقائي.

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

خدمة الوصول إلى 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 isn't supported لهذا التنفيذ المحلي بدون واجهة مستخدم. عليك إنشاء حساب خدمة وتنزيل ملف المفتاح الخاص بتنسيق 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 الحصول على إعدادات التحسينات التلقائية، بما في ذلك تعديلات السلع وتحسينات الصور وتحسينات الشحن