دمج واجهة برمجة التطبيقات و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" لتخصيص عملية الإعداد بما يتناسب مع سير العمل المفضّل لديك:

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

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

وثائق مطوّري Merchant API على خادم MCP

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

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

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

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

يمكنك أن تطلب من الموظف نقل رمز دمج Content API for Shopping products.insert إلى 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 عيّنات التعليمات البرمجية ذات الصلة من مستودعات 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، وتقديم مثال على كيفية تنظيم الطلب المتعدد الأجزاء. ويحوّل ذلك مهمة نقل البيانات التي قد تكون مربكة إلى عملية إرشادية.

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

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

آلية العمل

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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