دمج واجهة برمجة التطبيقات و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 وغيرها.
  • تحديد المشاكل وحلّها: تساعد في تشخيص الأخطاء الشائعة في واجهة برمجة التطبيقات وحلّها.

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

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

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

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

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

لدمج "منصّة إدارة الموافقة" واستخدامها، اتّبِع الخطوات التالية:

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

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

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

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

السيناريو 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، التي تستخدم طرقًا محدّدة 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 مع مختلف أدوات سطر الأوامر وبيئات التطوير المتكاملة المستندة إلى الذكاء الاصطناعي، مثل Gemini وClaude Code.

آلية العمل

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

  • الإعداد بدون تدخل: يدير تلقائيًا عمليات الربط بخادم 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المهارةmapi-developer-assistant وتفعيلها في أدوات تطوير الذكاء الاصطناعي، يتم تفعيلها تلقائيًا عادةً عندما تطرح أسئلة متعلقة بواجهة Merchant API.

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

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

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

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

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

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

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