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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لربط بيئة التطوير المتكاملة أو مساعد الترميز أو الوكيل بخدمة Merchant API MCP Access، عدِّل إعدادات عميل MCP (مثل mcp.json أو settings.json).

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

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

{
    "mcpServers": {
        "merchant-api-access": {
            "serverUrl": "https://merchantapi.googleapis.com/mcp",
            "headers": {
                "Authorization": "Bearer {ACCESS_TOKEN}",
                "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
            }
        }
    }
}

claude mcp add --transport http merchant-api https://merchantapi.googleapis.com/mcp --scope local \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}"

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      }
    }
  }'

غيِّر القيم في السلسلة على الشكل التالي:

• ACCOUNT_ID: معرّف Merchant Center
• ACCESS_TOKEN: رمز التفويض لإجراء طلب البيانات من واجهة برمجة التطبيقات
• GOOGLE_CLOUD_PROJECT_ID: رقم تعريف مشروع على السحابة الإلكترونية من Google المرتبط بحسابك على Merchant Center

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

لتوضيح كيفية الاستفادة من خدمة الوصول إلى 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) والأوصاف

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