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 أو settings.json).

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

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

Antigravity

يمكنك الاتصال مباشرةً بنقطة نهاية MCP البعيدة المستضافة باستخدام رمز وصول OAuth 2.0 (بالنطاق https://www.googleapis.com/auth/content). يُرجى اتّباع التعليمات الواردة في مستندات Antigravity.

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

Claude CLI

يمكنك إضافة نقطة نهاية MCP البعيدة المستضافة مباشرةً في Claude CLI باستخدام الأمر claude mcp add:

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}"

يُرجى اتّباع التعليمات الواردة في مستندات Claude MCP documentation.

cURL

يمكنك إرسال طلبات JSON-RPC 2.0 العادية مباشرةً إلى نقطة نهاية MCP المستضافة في Merchant API.

عرض الأدوات المتاحة:

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": {}
  }'

تنفيذ طلب استخدام أداة (مثل list_data_sources):

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.

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

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