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

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

نظرة عامة

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

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

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

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

(Merchant API) مخطّط بياني لـ Code Assist في عملية دمج الذكاء الاصطناعي

خادم MCP لمستندات المطوّرين في Merchant API

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

آلية العمل

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

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

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

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

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

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

افتح بيئة تطوير متكاملة (IDE) أو مساعدة في البرمجة تتوافق مع بروتوكول سياق النموذج مع نقل HTTP قابل للبث.

2. ضبط نقطة النهاية

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

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

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

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

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

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

"نقل رمز products.insert إلى Merchant API"

من خلال تزويد وكيلك بتعليمات النظام وإذن الوصول إلى MCP، يمكن لوكيلك ترجمة رمز Content API for Shopping إلى رمز Merchant API مباشرةً في بيئة التطوير المتكاملة (IDE). في هذه الحالة، سيتم تحديد 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 عيّنات التعليمات البرمجية ذات الصلة من مستودعات Google الرسمية على GitHub وأدلة المطوّرين. يمكن للمساعد بعد ذلك تقديم مجموعة رموز برمجية كاملة وجاهزة للتعديل.

السيناريو 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، وتقديم مثال على كيفية تنظيم الطلب المتعدد الأجزاء. يؤدي ذلك إلى تحويل مهمة نقل البيانات التي قد تكون مربكة إلى عملية موجَّهة.

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

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

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

"Migrate this reporting query from Content API to 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 مع العديد من أدوات سطر الأوامر المستندة إلى الذكاء الاصطناعي وبيئات التطوير المتكاملة (IDE)، مثل Antigravity وClaude Code.

آلية العمل

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

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

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

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

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

يوفّر ملف Merchant API Agent Skills README إرشادات مفصّلة حول:

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