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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لربط بيئة التطوير المتكاملة (IDE) أو مساعدة في البرمجة أو الوكيل بخدمة 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}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

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}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: list_data_sources" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

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

لتوضيح كيفية الاستفادة من خدمة الوصول إلى 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: إنشاء مصادر البيانات واسترجاعها

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

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

"أريد إنشاء مصدر بيانات تكميلي باسم "تعديلات الأسعار" لحسابي على Merchant Center".

سلوك الوكيل مع بروتوكول MCP:

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

أدوات بروتوكول سياق النموذج (MCP) وأوصافها

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