API Integration and Code Assist Toolkit

از «کیت ابزار دستیار کد و ادغام میانای برنامه‌سازی کاربردی» برای تسریع انتقال به Merchant API و ساختن ادغام‌های جدید با ابزارهای توسعه هوش مصنوعی استفاده کنید.

نمای کلی

هنگام انتقال از Content API for Shopping به Merchant API یا ساختن یک ادغام جدید، باید ساختارهای سرویس جدید، نام‌های منابع، و روش‌ها را درک کنید. ابزارهای توسعه با پشتیبانی هوش مصنوعی به‌ویژه برای کمک به عملیات زیر مناسب هستند:

• ترجمه و انتقال کد: به شما کمک می‌کند کد قدیمی Content API for Shopping را درک کنید و آن را به قالب جدید Merchant API تبدیل کنید. این شامل نگاشت مشخصه‌های محصول به ساختار جدید و به‌روزرسانی فایل‌های مدیریت وابستگی می‌شود.
• تخصص در اسناد API: توضیحات واضحی درباره منابع، روش‌ها، فیلدها، سهمیه‌ها، و روال‌های مطلوب Merchant API براساس بافت معتبر از اسناد رسمی Google API ارائه می‌دهد.
• تولید کد: تکه‌کدهایی را برای تکالیف مختلف Merchant API به زبان‌های مختلف ازجمله Python،‏ Java،‏ PHP، و زبان‌های دیگر تولید می‌کند.
• عیب‌یابی: به تشخیص و رفع خطاهای رایج میانای برنامه‌سازی کاربردی کمک می‌کند.

گزینه‌ای را انتخاب کنید که با محیط توسعه نرم‌افزار و مورد استفاده خاص شما بیشترین تناسب را دارد. از «کیت ابزار دستیار کد و ادغام میانای برنامه‌سازی کاربردی» برای سفارشی‌سازی راه‌اندازی براساس گردش کار ترجیحی‌تان استفاده کنید:

• سرور MCP مستندات توسعه‌دهنده Merchant API برای بازیابی مستقیم بافتار
• مهارت‌های عامل Merchant API برای راهنمایی مبتنی بر گردش کار

نمودار زیر گزینه‌های راه‌اندازی برای انتقال کد با کمک هوش مصنوعی را در رایج‌ترین محیط‌های توسعه یکپارچه (IDE) مانند Antigravity،‏ Visual Studio Code،‏ Cursor، یا Copilot نشان می‌دهد. می‌توانید دستیارهای کدنویسی مثل Gemini،‏ Claude،‏ ChatGPT،‏ Grok را راه‌اندازی کنید و آن‌ها را با سرور MCP «مستندات توسعه‌دهنده Merchant API» یا «مهارت‌های عامل Merchant API» توانمند کنید تا ضمن افزایش سرعت ادغام، پایه‌گذاری بهتری داشته باشند.

توجه: شرایط خدمات Merchant API بر این سرویس حاکم است. این سرویس حریم خصوصی توسعه‌دهنده را در اولویت قرار می‌دهد و فقط اسناد معتبر و دردسترس عموم را براساس پُرسمان‌های صادرشده توسط دستیار کدنویسی شما بازیابی می‌کند. دستیاری که استفاده می‌کنید تعیین می‌کند چه پُرسمان‌هایی به سرویس ارسال شود. به‌عنوان روال مطلوب، از ارسال اطلاعات حساس یا اختصاصی خودداری کنید.

Merchant API Developer Documentation MCP Server

از دستیار کدنویسی دلخواهتان، اطلاعات زمینه‌ای درباره Merchant API دریافت کنید. اکنون می‌توانید در IDE خود بااستفاده از سرویس «پروتکل بافت مدل» (MCP) به مستندات توسعه‌دهنده دسترسی پیدا کنید. این سرویس اطلاعات کلیدی را از اسناد رسمی Google API به دستیار کدنویسی شما ارائه می‌دهد. برای اطلاعات بیشتر درباره خود پروتکل، به استاندارد Model Context Protocol مراجعه کنید.

روش کار

وقتی از دستیار کدنویسی IDE با MCP فعال‌شده سؤالی درباره Merchant API می‌پرسید، این سرویس مرتبط‌ترین قطعه‌های نوشتار و کد را از منابع رسمی بازیابی می‌کند و آن‌ها را به‌عنوان بافت بااستفاده از یک پس‌بک تخصصی «تولید با کمک بازیابی» (RAG) به دستیار کدنویسی شما برمی‌گرداند. سیستم «تولید افزوده بازیابی» سیستمی است که کیفیت پاسخ‌های مدل‌های زبانی بزرگ را با متصل کردن آن‌ها به منابع دانش خارجی و به‌روز بهبود می‌بخشد. این کار به دستیار شما امکان می‌دهد بدون اینکه لازم باشد محیط توسعه نرم‌افزارتان را ترک کنید، پاسخ‌های دقیق و به‌روز ارائه دهد.

نمونه گردش کار:

1. سؤالی را در «عامل» یا دستیار کدنویسی سازگار با MCP خود می‌پرسید (برای مثال، سؤال به زبان طبیعی، درخواست نمونه کد، یا ترجمه کد).
2. دستیار کدنویسی شما درخواستی برای بافتار به نقطه پایانی MCP ارسال می‌کند.
3. سرویس MCP مجموعه نمایه‌شده از اسناد، راهنماها، و نمونه کدهای رسمی Merchant API را جستجو می‌کند.
4. این سرویس گزیده‌های معتبر را به‌عنوان بافت به دستیار کدنویسی شما برمی‌گرداند.
5. دستیار کدنویسی شما از این بافت برای تولید پاسخ مستدل یا تکلیف ترجمه کد استفاده می‌کند.

درحال شروع کردن

برای ادغام و استفاده از MCP، این مراحل را دنبال کنید:

۱. از ابزار سازگار استفاده کنید

یک IDE یا دستیار کدنویسی را که از «پروتکل زمینه‌ای مدل» با انتقال HTTP جاری‌سازی‌شدنی پشتیبانی می‌کند باز کنید.

۲. پیکربندی نقطه پایان

برای متصل کردن IDE یا دستیار کدنویسی به MCP، از جزئیات نقطه پایانی راه دور ارائه‌شده استفاده کنید که ممکن است بسته به پیکربندی ابزارتان، لازم باشد نشانی وب سرویس مستقیم یا تعریف 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/"
  }
}

۳. افزودن دستورالعمل‌های عامل (اختیاری)

برای اینکه عاملتان بتواند مستقیماً کد را بااستفاده از MCP ترجمه کند، دستورالعمل‌های سیستم: پروتکل عامل ادغام‌کننده فروشنده را به آن ارائه دهید. این دستورالعمل‌ها به نماینده راهنمایی می‌کنند که چگونه به‌درستی از MCP برای ترجمه کد استفاده کند. بسته به ابزارتان، می‌توانید این دستورالعمل‌ها را در پیکربندی دستورالعمل‌های سیستم یا به‌عنوان فایل بافت اضافی برای نماینده ارائه دهید.

سناریوهای نمونه استفاده

MCP می‌تواند گردش کار شما را در موارد استفاده رایج زیر تسریع کند:

سناریو ۱: انتقال کد products.insert

می‌توانید از نماینده بخواهید کد ادغام Content API for Shopping products.insert را مستقیماً به Merchant API منتقل کند.

پیام‌واره کاربر:

«انتقال دادن کد products.insert به میانای برنامه‌سازی کاربردی بازرگان»

با ارائه دستورالعمل‌های سیستم و دسترسی به MCP به نماینده‌تان، نماینده‌تان می‌تواند کد Content API for Shopping را مستقیماً در IDE شما به کد Merchant API ترجمه کند. در این حالت، productInputs.insert را به‌عنوان فراخوانی معادل شناسایی می‌کند و مشخصه‌های محصول را از قالب قدیمی به قالب جدید موردنیاز Merchant API نگاشت می‌کند. همچنین می‌تواند واردات موردنیاز و فایل مدیریت وابستگی (برای مثال requirements.txt، pom.xml، یا package.json) را به‌روز کند. می‌توانید به نماینده دستور دهید تغییرات را در محل انجام دهد یا پوشه جدیدی ایجاد کند.

سناریو ۲: پیدا کردن عملکرد معادل

برنامه موجودی دارید که از Content API for Shopping استفاده می‌کند و باید آن را به‌روز کنید. می‌توانید درباره یک روش قدیمی خاص بپرسید تا جزئیات مربوط به پیاده‌سازی جدید و نمونه کد مرتبط را دریافت کنید.

پیام‌واره کاربر:

"What is the Merchant API equivalent for the accountstatuses.get method in the Content API for Shopping?"

سرویس MCP بافت را از راهنماهای رسمی انتقال و اسناد مرجع ارائه می‌دهد و به دستیار شما اجازه می‌دهد با پاسخی دقیق، ازجمله نام جدید API، accounts.issues، پاسخ دهد.

سناریو ۳: پیدا کردن نمونه کد

درحال پیاده‌سازی ویژگی جدیدی هستید و به نمونه‌ای کاربردی برای دنبال کردن نیاز دارید.

پیام‌واره کاربر:

«نمونه کد Python برای افزودن سرویس ارسال جدید بااستفاده از Merchant API به من نشان بده.»

سرویس MCP نمونه کدهای مربوطه را از مخازن رسمی Google GitHub و راهنماهای توسعه‌دهنده بازیابی می‌کند. سپس دستیارتان می‌تواند بلوک کد کامل و آماده برای اقتباس را ارائه دهد.

سناریو ۴: درک مفاهیم API

با مفهوم جدیدی مواجه می‌شوید یا می‌خواهید ساختار منبع یا الگوی کلی Merchant API را درک کنید.

پیام‌واره کاربر:

«چگونه موجودی محصولی را بااستفاده از Merchant API به‌روز کنم؟»

سرویس MCP بافت را از مستندات منبع محصولات و راهنماهای مربوطه برمی‌گرداند. سپس دستیارتان می‌تواند نحوه استفاده از روش accounts.productInputs.insert را توضیح دهد و منبع محصول جزئی را که فقط حاوی productId و فیلدهای مربوط به موجودی است که باید به‌روز کنید ارائه دهد.

«چگونه تماس‌های برنامه‌ام را با Merchant API مجاز کنم؟»

سرویس MCP بافت را از راهنماهای رسمی اصالت‌سنجی بازیابی می‌کند که روش‌های مختلف صدور مجوز را پوشش می‌دهند. سپس دستیار شما می‌تواند گزینه‌های اصلی موجود را توضیح دهد، مانند استفاده از حساب سرویس برای تعاملات سرور به سرور یا شناسه کارخواه OAuth 2.0 هنگام اقدام ازطرف کاربر.

سناریو ۵: سازگار شدن با تغییرات میانای برنامه‌سازی کاربردی

Merchant API الگوهای جدیدی را معرفی می‌کند — مثل درخواست‌های دسته‌ای — که با «میانای برنامه‌سازی کاربردی محتوا برای خرید» متفاوت است. «میانای برنامه‌سازی کاربردی محتوا برای خرید» از روش‌های خاص custombatch استفاده می‌کند، درحالی‌که Merchant API از ویژگی گروه‌بندی HTTP داخلی و عمومی استفاده می‌کند.

پیام‌واره کاربر:

«روش جدید برای انجام products.custombatch در Merchant API چیست؟»

سرویس MCP بافت را از کد بازسازی‌شده برای درخواست‌های هم‌زمان بازیابی می‌کند و توضیح می‌دهد که روش‌های اختصاصی custombatch در Merchant API وجود ندارد. درعوض، اسنادی درباره استفاده از دسته‌بندی HTTP با Content-Type multipart ارائه می‌دهد. سپس دستیار شما می‌تواند توضیح دهد که چگونه یک درخواست HTTP واحد حاوی چندین فراخوانی API بسازید، آن را به نقطه پایانی 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 به‌عنوان یک لایه هوشمند بین ابزارهای توسعه هوش مصنوعی شما و Merchant API Dev Doc MCP Server زیربنایی عمل می‌کند. این مدل تخصص دامنه و راهنمایی رویه‌ای را در خود جای داده است و ویژگی‌های زیر را دارد:

• پیکربندی صفر: اتصال‌های «سرور MCP» را به‌طور خودکار مدیریت می‌کند و نیاز به راه‌اندازی دستی نقطه پایانی را ازبین می‌برد.
• گردش کار کارشناس: پیام‌واره‌های کاربر را به پُرسمان‌های بهینه‌شده تبدیل می‌کند تا مرتبط‌ترین اطلاعات را به‌طور مؤثر واکشی کند.
• مدیریت بافت و کارایی توکن: از «شفاف‌سازی تدریجی» برای بار کردن اطلاعات درصورت درخواست و حفظ پنجره بافت هوش مصنوعی استفاده می‌کند.
• قالب‌بندی خروجی بهبودیافته: دستورالعمل‌هایی برای قالب‌بندی و ساختاردهی خروجی برای پاسخ‌های قابل‌اجرا، خوانا، و منسجم ارائه می‌دهد.

نمونه گردش کار:

1. در ابزار توسعه هوش مصنوعی، سؤالی درباره Merchant API می‌پرسید.
2. مهارت عامل Merchant API قصد شما را تحلیل می‌کند، پُرسمان دقیقی را فرمول‌بندی می‌کند، و دانش رویه‌ای خود را بر درخواست اعمال می‌کند.
3. «مهارت عامل» درخواستی برای زمینه به Merchant API Dev Doc MCP Server واقع در merchantapi.googleapis.com/devdocs/mcp/ ارسال می‌کند.
4. سرویس MCP مجموعه نمایه‌شده از اسناد، راهنماها، و نمونه کدهای رسمی Merchant API را جستجو می‌کند.
5. «عامل هوش مصنوعی» شما از این اطلاعات برای ارائه پاسخی ترکیبی و قابل‌اجرا استفاده می‌کند.

درحال شروع کردن

Merchant API Agent Skills README راهنمایی گام‌به‌گام درباره موارد زیر ارائه می‌دهد:

• پیش‌نیازهای ابزارهایی مانند ابزار خط فرمان Antigravity.
• درحال فعال کردن پشتیبانی از «مهارت‌های نماینده» در ابزار انتخابی شما.
• Installing the mapi-developer-assistant skill from the GitHub repository as guided by the README.
• درحال درستی‌سنجی نصب.
• فرمان‌های مدیریت مهارت پایه.

برای دستورالعمل‌های دقیق نصب و راه‌اندازی ابزارهای مختلف هوش مصنوعی، ازجمله ابزار خط فرمان Antigravity،‏ Claude Code، و غیره، راهنمایی‌های موجود در فایل README را دنبال کنید.

پیام‌واره‌های نمونه

پس‌از نصب و فعال‌سازی در ابزارهای توسعه هوش مصنوعی، مهارت mapi-developer-assistant معمولاً به‌طور خودکار فعال می‌شود وقتی‌که پرسش‌های مربوط به Merchant API را می‌پرسید.

«چگونه بااستفاده از Merchant API در Python محصول درج کنم؟»

«معادل Merchant API برای روش Content API accountstatuses.get چیست؟»

«نمونه‌ای از Java برای مدیریت اصالت‌سنجی با Merchant API به من نشان بده.»

«هنگام تماس با productInputs.insert، خطای «۴۰۰ درخواست بد» با خطای اعتبارسنجی دریافت می‌کنم. چگونه این مشکل را حل کنم؟»

«تفاوت بین ProductInput و Product در Merchant API چیست؟»

منابع پایگاه دانش

سرویس MCP پایگاه دانش خود را منحصراً از منابع عمومی و رسمی می‌سازد تا مطمئن شود زمینه‌ای که ارائه می‌دهد دقیق و قابل‌اعتماد است. این سرویس کل محتوای سایت رسمی توسعه‌دهنده و مخزن نمونه کد را نمایه‌سازی می‌کند، ازجمله:

• سایت توسعه‌دهنده Merchant API: همه راهنماها، مطالب مرجع، و اسناد.
• سرویس Merchant API Apps Script: نمونه‌ای از استفاده از Merchant API از Apps Script.
• نمونه‌های کد رسمی: همه نمونه‌های کد رسمی ارائه‌شده توسط Google برای Merchant API از مخزن GitHub.
• کتابخانه‌های کارخواه: همه کتابخانه‌های کارخواه رسمی که Merchant API از آن‌ها پشتیبانی می‌کند.