دمج واجهة برمجة التطبيقات وCode Assist Toolkit

استخدِم مجموعة أدوات "دمج واجهة برمجة التطبيقات" وCode Assist لتسريع عملية نقل بياناتك إلى Merchant API وإنشاء عمليات دمج جديدة باستخدام أدوات التطوير المستندة إلى الذكاء الاصطناعي.

نظرة عامة

عند نقل البيانات من Content API for Shopping إلى Merchant API أو إنشاء عملية دمج جديدة، عليك فهم بُنى الخدمات الجديدة وأسماء الموارد والطُرق. تساعد أدوات التطوير المستندة إلى الذكاء الاصطناعي بشكل خاص في العمليات التالية:

  • ترجمة الرموز البرمجية ونقلها: تساعدك هذه الأدوات في فهم الرموز البرمجية القديمة في Content API for Shopping وتحويلها إلى تنسيق Merchant API الجديد. ويشمل ذلك ربط سمات المنتجات بالبنية الجديدة وتعديل ملفات إدارة التبعيات.
  • الخبرة في مستندات واجهة برمجة التطبيقات: تقدّم هذه الأدوات تفسيرات واضحة لموارد Merchant API وطُرقها وحقولها وحصصها وأفضل ممارساتها استنادًا إلى سياق موثوق من مستندات Google API الرسمية.
  • إنشاء الرموز البرمجية: تنشئ هذه الأدوات مقتطفات رموز برمجية لمختلف مهام Merchant API بـ لغات مثل Python وJava وPHP ولغات أخرى.
  • تحديد المشاكل وحلّها: تساعد هذه الأدوات في تشخيص أخطاء واجهة برمجة التطبيقات الشائعة وحلّها.

اختَر الخيار الذي يناسب بيئة التطوير وحالة الاستخدام المحدّدة. استخدِم مجموعة أدوات "دمج واجهة برمجة التطبيقات" وCode Assist لتخصيص الإعدادات بما يتناسب مع سير العمل المفضّل لديك:

يوضّح الرسم البياني التالي خيارات الإعداد لنقل الرموز البرمجية بمساعدة الذكاء الاصطناعي في بيئات التطوير المتكاملة (IDEs) الأكثر استخدامًا، مثل Antigravity أو Visual Studio Code أو Cursor أو Copilot. يمكنك إعداد مساعدين للترميز، مثل Gemini وClaude وChatGPT وGrok، وتزويدهم بخادم Model Context Protocol ‏(MCP) في مستندات المطوّرين لواجهة Merchant API أو مهارات الوكيل في Merchant API ليكونوا أكثر استنادًا إلى الحقائق مع زيادة سرعة عمليات الدمج.

(Merchant API) مخطط "مساعد الترميز المستنِد إلى الذكاء الاصطناعي"

خادم Model Context Protocol ‏(MCP) في مستندات المطوّرين لواجهة Merchant API

يمكنك الحصول على معلومات سياقية حول Merchant API من مساعد الترميز الذي تختاره. ضمن بيئة التطوير المتكاملة، يمكنك الآن الوصول إلى مستندات المطوّرين باستخدام خدمة Model Context Protocol ‏ (MCP). تزوّد هذه الخدمة مساعد الترميز بمعلومات أساسية من مستندات Google API الرسمية. لمزيد من المعلومات عن البروتوكول نفسه، اطّلِع على معيار Model Context Protocol.

آلية العمل

عندما تطرح سؤالاً على مساعد الترميز في بيئة التطوير المتكاملة التي تستخدم بروتوكول MCP حول Merchant API، تسترجِع الخدمة أكثر مقتطفات النصوص والرموز البرمجية ملاءمةً من المصادر الرسمية وتعرضها كسياق لمساعد الترميز باستخدام نظام خلفية متخصص في التوليد المعزّز بالاسترجاع (RAG). نظام RAG هو نظام يحسّن جودة الردود من النماذج اللغوية الكبيرة من خلال ربطها بمصادر خارجية للمعلومات محدَّثة باستمرار. يمنح ذلك المساعد إمكانية تقديم إجابات دقيقة ومحدَّثة بدون الحاجة إلى مغادرة بيئة التطوير.

مثال على سير العمل:

  1. تطرح سؤالاً في مساعد الترميز أو الوكيل المتوافق مع بروتوكول MCP (مثلاً، سؤال باللغة الطبيعية أو طلب للحصول على عينة رمز برمجية أو ترجمة رمز برمجية).
  2. يرسل مساعد الترميز طلبًا للحصول على السياق إلى نقطة نهاية MCP.
  3. تبحث خدمة MCP في مجموعتها المفهرسة من مستندات Merchant API الرسمية والأدلة وعيّنات الرموز البرمجية.
  4. تعرض الخدمة مقتطفات موثوقة كسياق لمساعد الترميز.
  5. يستفيد مساعد الترميز من هذا السياق لإنشاء إجابة مستندة إلى الحقائق أو مهمة ترجمة رمز برمجية.

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

لدمج بروتوكول MCP واستخدامه، اتّبِع الخطوات التالية:

1- استخدام أداة متوافقة

افتح بيئة تطوير متكاملة أو مساعد ترميز يتوافق مع بروتوكول Model Context Protocol مع نقل HTTP قابل للبث.

2- إعداد نقطة النهاية

لربط بيئة التطوير المتكاملة أو مساعد الترميز ببروتوكول MCP، استخدِم تفاصيل نقطة النهاية البعيدة المقدَّمة التي قد تتطلب منك إدخال عنوان URL المباشر للخدمة أو تعريف MCP، حسب إعدادات أداتك:

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

Antigravity

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

"mcpServers": {
  "mapi-devdocs": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://merchantapi.googleapis.com/devdocs/mcp"
    ]
  }
}

محرِّر Visual Studio Code

اتّبِع التعليمات الواردة في مستندات Visual Studio Code.

"servers": {
"mapi-devdocs": {
  "type": "http",
  "url": "https://merchantapi.googleapis.com/devdocs/mcp/"
  }
}

3- إضافة تعليمات الوكيل (اختياري)

لتمكين الوكيل من ترجمة الرموز البرمجية مباشرةً باستخدام بروتوكول MCP، زوِّده بالـ تعليمات النظام: بروتوكول وكيل دمج التجّار. توجّه هذه التعليمات الوكيل بشأن كيفية استخدام بروتوكول MCP بشكل صحيح لترجمة الرموز البرمجية. حسب الأداة التي تستخدمها، يمكنك تقديم هذه التعليمات إما في إعدادات تعليمات النظام أو كملف سياق إضافي للوكيل.

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

يمكن أن يسرّع بروتوكول MCP سير عملك في حالات الاستخدام الشائعة التالية:

السيناريو 1: نقل الرمز البرمجي products.insert

يمكنك أن تطلب من الوكيل نقل رمز دمج products.insert من Content API for Shopping إلى Merchant API مباشرةً.

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

"نقل الرمز البرمجي products.insert إلى Merchant API"

من خلال تزويد الوكيل بتعليمات النظام وإمكانية الوصول إلى بروتوكول MCP، يمكنه ترجمة الرمز البرمجي من Content API for Shopping إلى Merchant API مباشرةً في بيئة التطوير المتكاملة. في هذه الحالة، سيحدّد الوكيل productInputs.insert باعتباره الطلب المكافئ ويربط سمات المنتجات من التنسيق القديم بالتنسيق الجديد المطلوب من Merchant API. يمكنه أيضًا تعديل عمليات الاستيراد المطلوبة وملف إدارة التبعيات (مثل requirements.txt أو pom.xml أو package.json). يمكنك توجيه الوكيل لإجراء التغييرات في مكانها أو إنشاء مجلد جديد.

السيناريو 2: العثور على وظائف مكافئة

لديك تطبيق حالي يستخدم Content API for Shopping وتحتاج إلى تعديله. يمكنك طرح سؤال عن طريقة قديمة محدّدة للحصول على تفاصيل حول التنفيذ الجديد وعينة رمز برمجية ذات صلة.

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

"ما هو الطلب المكافئ في Merchant API للطريقة accountstatuses.get في Content API for Shopping؟"

تقدّم خدمة MCP سياقًا من أدلة النقل والمستندات المرجعية الرسمية، ما يتيح للمساعد الردّ بإجابة مفصّلة، بما في ذلك اسم واجهة برمجة التطبيقات الجديدة، accounts.issues.

السيناريو 3: العثور على عينة رمز برمجية

أنت بصدد تنفيذ ميزة جديدة وتحتاج إلى مثال عملي لتتبّعه.

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

"أرني عينة رمز برمجية بلغة Python لإضافة خدمة شحن جديدة باستخدام Merchant API."

تسترجِع خدمة MCP عيّنات الرموز البرمجية ذات الصلة من مستودعات GitHub الرسمية من Google وأدلة المطوّرين. يمكن للمساعد بعد ذلك عرض كتلة رموز برمجية كاملة وجاهزة للتعديل.

السيناريو 4: فهم مفاهيم واجهة برمجة التطبيقات

تواجه مفهومًا جديدًا أو تريد فهم بنية مورد أو النمط العام لواجهة Merchant API.

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

"كيف يمكنني تعديل المخزون لمنتج باستخدام Merchant API؟"

تعرض خدمة MCP سياقًا من مستندات مورد المنتجات والأدلة ذات الصلة. يمكن للمساعد بعد ذلك شرح كيفية استخدام الطريقة accounts.productInputs.insert وتقديم مورد المنتج الجزئي الذي يحتوي فقط على productId والحقول ذات الصلة بالمخزون التي تحتاج إلى تعديلها.

"كيف يمكنني تفويض طلبات بيانات من تطبيقي باستخدام Merchant API؟"

تسترجِع خدمة MCP سياقًا من أدلة المصادقة الرسمية التي تتناول طُرق التفويض المختلفة. يمكن للمساعد بعد ذلك شرح الخيارات الأساسية المتاحة، مثل استخدام حساب خدمة للتفاعلات بين الخادم والخادم أو معرّف عميل OAuth 2.0 عند التصرف نيابةً عن مستخدِم.

السيناريو 5: التكيّف مع التغييرات في واجهة برمجة التطبيقات

تقدّم Merchant API أنماطًا جديدة، مثل تجميع الطلبات في دُفعات، تختلف عن Content API for Shopping. تستخدم Content API for Shopping طُرقًا محدّدة لـ custombatch، بينما تستخدم Merchant API ميزة مدمجة وعامة لتجميع طلبات HTTP في دُفعات.

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

"ما هي الطريقة الجديدة لتنفيذ `products.custombatch` في Merchant API؟"

تسترجِع خدمة MCP سياقًا من مقالة إعادة تصميم الرموز البرمجية للطلبات المتزامنة التي توضّح أنّه لا تتوفّر طُرق custombatch مخصّصة في Merchant API. بدلاً من ذلك، تقدّم الخدمة مستندات حول استخدام تجميع طلبات HTTP في دُفعات مع Content-Type بقيمة multipart. يمكن للمساعد بعد ذلك شرح كيفية إنشاء طلب HTTP واحد يحتوي على طلبات بيانات متعددة من واجهة برمجة التطبيقات، يتم إرسالها إلى نقطة النهاية https://merchantapi.googleapis.com/batch/{sub-api}/v1، وتقديم مثال على كيفية تنظيم الطلب المتعدد الأجزاء. يحوّل ذلك مهمة نقل البيانات التي قد تكون مربكة إلى عملية موجَّهة.

السيناريو 6: ترجمة طلب إعداد تقارير

يمكنك أن تطلب من الوكيل ترجمة طلب إعداد تقارير من Content API for Shopping إلى Merchant API.

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

"نقل طلب إعداد التقارير هذا من Content API إلى Merchant API: SELECT metrics.impressions, metrics.clicks, metrics.ctr FROM MerchantPerformanceView WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-30'"

تسترجِع خدمة MCP أحدث المستندات المرجعية لإعداد التقارير وأدلة المطوّرين وأدلة نقل البيانات. استنادًا إلى هذه المعلومات، تحوّل الخدمة طلب البحث إلى البنية الجديدة وتعدّل الحقول إلى أسمائها وقيمها الجديدة.

مهارات الوكيل في Merchant API

مواصفات مهارات الوكيل هي معيار مفتوح تم اعتماده في جميع أدوات تطوير الذكاء الاصطناعي. استخدِم مهارات الوكيل لتحسين تجربة المطوّرين وتحسين كلٍّ من عملية نقل البيانات من Content API for Shopping وإنشاء عمليات دمج جديدة. تجمع مهارات الوكيل في Merchant API المعرفة والأدوات الخاصة بالمجال لتعزيز إمكانات وكلاء الذكاء الاصطناعي وتقدّم مساعدة احترافية عند الطلب لطلبات البحث عن المستندات وإنشاء الرموز البرمجية وتحديد المشاكل وحلّها.

تتوافق مهارات الوكيل في Merchant API مع مختلف أدوات سطر الأوامر وبيئات التطوير المتكاملة المستندة إلى الذكاء الاصطناعي، مثل أداة Antigravity لسطر الأوامر وClaude Code.

آلية العمل

تقدّم مهارات الوكيل في Merchant API حزمة خبرة متخصّصة تستند إلى معيار مهارات الوكيل المفتوح. تعمل مهارة الوكيل mapi-developer-assistant كطبقة ذكية بين أدوات تطوير الذكاء الاصطناعي وخادم Model Context Protocol ‏(MCP) في مستندات المطوّرين لواجهة Merchant API الأساسية. تتضمّن هذه المهارة خبرة في المجال وإرشادات إجرائية، ولها الخصائص التالية:

  • بدون إعداد: تدير هذه المهارة تلقائيًا اتصالات خادم MCP، ما يزيل الحاجة إلى إعداد نقطة النهاية يدويًا.
  • سير عمل الخبراء: تحسّن هذه المهارة طلبات المستخدمين إلى طلبات بحث محسّنة لاسترجاع المعلومات الأكثر ملاءمةً بفعالية.
  • إدارة السياق وكفاءة الرموز المميّزة: تستخدِم هذه المهارة ميزة "الكشف التدريجي" لتحميل المعلومات عند الطلب والحفاظ على نافذة سياق الذكاء الاصطناعي.
  • تنسيق محسّن للناتج: تقدّم هذه المهارة تعليمات لتنسيق وتنظيم الناتج من أجل الحصول على ردود قابلة للتنفيذ وقابلة للقراءة ومتّسقة.

مثال على سير العمل:

  1. تطرح سؤالاً عن Merchant API في أداة تطوير الذكاء الاصطناعي.
  2. تحلّل مهارة الوكيل في Merchant API هدفك وتصوغ طلب بحث دقيقًا وتطبّق معرفتها الإجرائية على الطلب.
  3. ترسل مهارة الوكيل طلبًا للحصول على السياق إلى خادم Model Context Protocol ‏(MCP) في مستندات المطوّرين لواجهة Merchant API الذي يقع على merchantapi.googleapis.com/devdocs/mcp/.
  4. تبحث خدمة MCP في مجموعتها المفهرسة من مستندات Merchant API الرسمية والأدلة وعيّنات الرموز البرمجية.
  5. يستفيد وكيل الذكاء الاصطناعي من هذه المعلومات لتقديم ردّ مُجمَّع وقابل للتنفيذ.

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

يقدّم ملف README الخاص بمهارات الوكيل في Merchant API إرشادات مفصّلة حول ما يلي:

  • المتطلبات الأساسية للأدوات، مثل أداة Antigravity لسطر الأوامر
  • تفعيل دعم مهارات الوكيل في الأداة التي تختارها
  • تثبيت مهارة mapi-developer-assistant من مستودع GitHub كما هو موضّح في ملف README
  • التحقّق من عملية التثبيت
  • الأوامر الأساسية لإدارة المهارات

للحصول على تعليمات مفصّلة حول التثبيت والإعداد لمختلف أدوات الذكاء الاصطناعي، بما في ذلك أداة Antigravity لسطر الأوامر وClaude Code وغيرها، اتّبِع الإرشادات الواردة في ملف README.

أمثلة على الطلبات

بعد تثبيت مهارة mapi-developer-assistant وتفعيلها في أدوات تطوير الذكاء الاصطناعي، يتم تفعيلها تلقائيًا عادةً عند طرح أسئلة متعلقة بـ Merchant API.

"كيف يمكنني إدراج منتج باستخدام Merchant API في Python؟"

ما هو الطلب المكافئ في Merchant API للطريقة accountstatuses.get في Content API؟

"أرني مثالاً بلغة Java للتعامل مع المصادقة باستخدام Merchant API."

تظهر لي رسالة الخطأ "400: طلب غير صالح" مع خطأ في التحقّق من الصحة عند طلب productInputs.insert. كيف يمكنني حلّ هذه المشكلة؟"

ما الفرق بين ProductInput وProduct في Merchant API؟

مصادر قاعدة المعلومات

تنشئ خدمة MCP قاعدة معلوماتها حصريًا من المصادر العامة والرسمية لضمان دقة السياق الذي تقدّمه وموثوقيته. تفهرس الخدمة المحتوى الكامل لموقع المطوّرين الرسمي ومستودع عيّنات الرموز البرمجية، بما في ذلك: