שילוב API וערכת כלים לסיוע בכתיבת קוד

ערכת הכלים לשילוב API ולעזרה בתכנות מאפשרת להאיץ את המעבר ל-Merchant API ולבנות שילובים חדשים בעזרת כלי פיתוח מבוססי-AI.

סקירה כללית

כשעוברים מ-Content API for Shopping ל-Merchant API או כשיוצרים שילוב חדש, חשוב להבין את המבנים החדשים של השירות, את שמות המשאבים ואת השיטות. כלי פיתוח מבוססי-AI מתאימים במיוחד לפעולות הבאות:

  • המרת קוד והעברת נתונים: עוזרת לכם להבין את הקוד הקודם של Content API for Shopping ולהמיר אותו לפורמט החדש של Merchant API. זה כולל מיפוי של מאפייני המוצר למבנה החדש ועדכון של קובצי ניהול התלויות.
  • מומחיות במאמרי העזרה של ה-API: מספק הסברים ברורים על המשאבים, השיטות, השדות, המכסות והשיטות המומלצות של Merchant API, על סמך הקשרים סמכותיים ממאמרי העזרה הרשמיים של Google API.
  • יצירת קוד: יוצר קטעי קוד למשימות שונות של Merchant API בשפות כמו Python,‏ Java,‏ PHP ושפות אחרות.
  • פתרון בעיות: עוזר לנתח ולתקן שגיאות נפוצות ב-API.

בוחרים את האפשרות שהכי מתאימה לסביבת הפיתוח ולתרחיש לדוגמה הספציפי. אתם יכולים להשתמש ב-API Integration and Code Assist Toolkit כדי להתאים את ההגדרה לתהליך העבודה המועדף עליכם:

בתרשים הבא מוצגות אפשרויות ההגדרה להעברת קוד בעזרת AI בסביבות הפיתוח המשולבות (IDE) הנפוצות ביותר, כמו Antigravity, ‏Visual Studio Code, ‏Cursor או Copilot. אפשר להגדיר עוזרי תכנות כמו Gemini,‏ Claude,‏ ChatGPT ו-Grok, ולתת להם גישה לשרת ה-MCP של מאמרי העזרה למפתחים של Merchant API או לכישורים של סוכן Merchant API כדי לשפר את הדיוק ולהאיץ את תהליך ההטמעה.

‫(Merchant API) תרשים של AI Integration Code Assist

שרת MCP של מאמרי העזרה למפתחים של Merchant API

אתם יכולים לקבל מידע קונטקסטואלי על Merchant API מעוזר התכנות שבחרתם. בסביבת הפיתוח המשולבת (IDE), אתם יכולים לגשת למאמרי העזרה למפתחים באמצעות שירות Model Context Protocol‏ (MCP). השירות הזה מספק לעוזר הדיגיטלי לתכנות מידע חשוב ממאמרי העזרה הרשמיים של Google API. מידע נוסף על הפרוטוקול עצמו זמין בתקן Model Context Protocol.

איך זה עובד

כששואלים את העזרה בתכנות של סביבת הפיתוח המשולבת (IDE) עם MCP שאלה לגבי Merchant API, השירות מאחזר את קטעי הטקסט והקוד הכי רלוונטיים ממשאבים רשמיים ומחזיר אותם כהקשר לעזרה בתכנות באמצעות קצה עורפי מיוחד של Retrieval-Augmented Generation‏ (RAG). מערכת RAG משפרת את איכות התשובות של מודלי LLM על ידי קישור שלהם למקורות ידע חיצוניים ועדכניים. כך העוזר הדיגיטלי יכול לספק תשובות מדויקות ועדכניות בלי שתצטרכו לצאת מסביבת הפיתוח.

תהליך עבודה לדוגמה:

  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, צריך לספק לו את הוראות המערכת: פרוטוקול הנציג לשילוב עם Merchant. ההוראות האלה מסבירות לסוכן איך להשתמש ב-MCP בצורה נכונה להמרת קוד. בהתאם לכלי שבו אתם משתמשים, אתם יכולים לתת את ההוראות האלה בהגדרות של הוראות המערכת או כקובץ הקשר נוסף לסוכן.

תרחישי שימוש לדוגמה

‫MCP יכול להאיץ את תהליך העבודה בתרחישים הנפוצים הבאים:

תרחיש 1: העברת קוד products.insert

אתם יכולים לבקש מהנציג להעביר ישירות קוד שילוב של Content API for Shopping ל-Merchant API. products.insert

הנחיית המשתמש:

"העברת הקוד של 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 מספק הקשר מהמדריכים הרשמיים להעברת נתונים וממאמרי העזרה, ומאפשר לעוזר הדיגיטלי להשיב בתשובה מפורטת, כולל שם ה-API החדש, accounts.issues.

תרחיש 3: חיפוש דוגמת קוד

אתם מטמיעים תכונה חדשה וצריכים דוגמה מעשית.

הנחיית המשתמש:

"הצג לי דוגמת קוד ב-Python להוספת שירות משלוחים חדש באמצעות Merchant API".

שירות ה-MCP מאחזר דוגמאות קוד רלוונטיות מהמאגרים הרשמיים של Google ב-GitHub ומהמדריכים למפתחים. ה-Assistant יכולה להציג בלוק קוד שלם שמוכן להתאמה.

תרחיש 4: הבנת מושגי API

אתם נתקלים במושג חדש או רוצים להבין את המבנה של משאב או את התבנית הכללית של Merchant API.

הנחיית המשתמש:

"איך מעדכנים את המלאי של מוצר באמצעות Merchant API?"

שירות ה-MCP מחזיר הקשר מתיעוד המשאבים של המוצרים ומהמדריכים הרלוונטיים. העוזר הדיגיטלי יכול להסביר איך להשתמש ב-method‏ accounts.productInputs.insert ולספק את משאב המוצר החלקי שמכיל רק את productId ואת השדות שקשורים למלאי שצריך לעדכן.

"איך מאשרים את הקריאות של האפליקציה באמצעות Merchant API?"

שירות ה-MCP מאחזר הקשר ממדריכי האימות הרשמיים, שכוללים שיטות הרשאה שונות. העוזר הדיגיטלי יכול להסביר את האפשרויות העיקריות שזמינות, כמו שימוש בחשבון שירות לאינטראקציות משרת לשרת או מזהה לקוח OAuth 2.0 כשפועלים בשם משתמש.

תרחיש 5: התאמה לשינויים ב-API

ב-Merchant API יש דפוסים חדשים, כמו בקשות Batch, ששונים מאלה של Content API for Shopping. ב-Content API for Shopping משתמשים בשיטות custombatch ספציפיות, וב-Merchant API משתמשים בתכונה מובנית וגנרית של HTTP לעבודה עם קבוצות.

הנחיית המשתמש:

"איך מבצעים products.custombatch ב-Merchant API החדש?"

שירות ה-MCP מאחזר הקשר מהמאמר Refactor code for concurrent requests, שבו מוסבר ששיטות custombatch ייעודיות לא קיימות ב-Merchant API. במקום זאת, הוא מספק תיעוד על השימוש באצווה של HTTP עם Content-Type של multipart. העוזר הדיגיטלי יכול להסביר איך ליצור בקשת HTTP אחת שמכילה כמה קריאות ל-API, שנשלחת לנקודת הקצה (endpoint) של 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

המפרט של Agent Skills הוא תקן פתוח שאומץ בכל הכלים למפתחים של AI. אתם יכולים להשתמש ב-Agent Skills כדי לשפר את חוויית הפיתוח ולבצע אופטימיזציה גם למעבר מ-Content API for Shopping וגם ליצירת שילובים חדשים. ‫Merchant API Agent Skills כולל חבילות של ידע וכלים ספציפיים לתחום שמשפרים את היכולות של סוכני AI, ומספק עזרה לפי דרישה ממומחים לשאילתות בנושא מסמכי תיעוד, יצירת קוד ופתרון בעיות.

הכישורים של סוכן Merchant API תואמים למגוון כלים מבוססי-AI בשורת הפקודה ולסביבות פיתוח משולבות (IDE) כמו Antigravity ו-Claude Code.

איך זה עובד

הסקילים של Merchant API Agent מספקים חבילת מומחיות ייעודית שמבוססת על התקן הפתוח של Agent Skills. הסקיל של הסוכן mapi-developer-assistant פועל כשכבה חכמה בין כלי הפיתוח של ה-AI לבין שרת ה-MCP של מסמכי הפיתוח של Merchant API. הוא כולל מומחיות בתחום והנחיות פרוצדורליות, ויש לו את המאפיינים הבאים:

  • אפס הגדרות: החיבורים לשרת ה-MCP מנוהלים באופן אוטומטי, ואין צורך להגדיר נקודות קצה באופן ידני.
  • תהליכי עבודה של מומחים: משפרים את ההנחיות של המשתמשים והופכים אותן לשאילתות אופטימליות כדי לאחזר את המידע הכי רלוונטי בצורה יעילה.
  • ניהול הקשר ושימוש יעיל בטוקנים: המערכת משתמשת ב"חשיפה הדרגתית" כדי לטעון מידע לפי דרישה ולשמור על חלון ההקשר של ה-AI.
  • עיצוב פלט משופר: הנחיות לעיצוב הפלט כדי לקבל תשובות קריאות, עקביות ופרקטיות.

תהליך עבודה לדוגמה:

  1. אתם שואלים שאלה על Merchant API בכלי למפתחים מבוסס-AI.
  2. הסוכן של Merchant API מנתח את הכוונה שלכם, מנסח שאילתה מדויקת ומיישם את הידע הפרוצדורלי שלו על הבקשה.
  3. ה-Agent Skill שולח בקשה להקשר אל שרת ה-MCP של מסמכי הפיתוח של Merchant API שנמצא בכתובת merchantapi.googleapis.com/devdocs/mcp/.
  4. שירות ה-MCP מחפש באוסף המאמרים, המדריכים ודוגמאות הקוד הרשמיים של Merchant API שנוספו לאינדקס.
  5. סוכן ה-AI שלך ממנף את המידע הזה כדי לספק תגובה מסוכמת ופרקטית.

תחילת העבודה

בקובץ ה-README של Merchant API Agent Skills יש הוראות מפורטות בנושאים הבאים:

  • דרישות מוקדמות לכלים כמו כלי שורת הפקודה Antigravity.
  • הפעלת התמיכה במיומנויות של סוכנים בכלי שבחרתם.
  • התקנת המיומנות mapi-developer-assistant ממאגר GitHub לפי ההוראות בקובץ README.
  • אימות ההתקנה.
  • פקודות בסיסיות לניהול מיומנויות.

הוראות מפורטות להתקנה ולהגדרה של כלי AI שונים, כולל כלי שורת הפקודה Antigravity,‏ Claude Code ואחרים, מופיעות בקובץ README.

הנחיות לדוגמה

אחרי שמתקינים ומפעילים את המיומנות mapi-developer-assistant בכלי הפיתוח של ה-AI, היא בדרך כלל מופעלת באופן אוטומטי כששואלים שאלות שקשורות ל-Merchant API.

"איך מוסיפים מוצר באמצעות Merchant API ב-Python?"

"מהי השיטה המקבילה ב-Merchant API לשיטה accountstatuses.get ב-Content API?"

"תראה לי דוגמה ב-Java לטיפול באימות באמצעות Merchant API".

"אני מקבל את השגיאה '400 Bad Request' עם שגיאת אימות כשאני מתקשר אל productInputs.insert. איך אפשר לתקן את זה?"

"מה ההבדל בין ProductInput לבין Product ב-Merchant API?"

מקורות של מאגר הידע

כדי להבטיח שההקשר שהוא מספק מדויק ומהימן, שירות ה-MCP בונה את מאגר הידע שלו אך ורק ממקורות ציבוריים ורשמיים. השירות מוסיף לאינדקס את כל התוכן של אתר המפתחים הרשמי ושל מאגר דוגמאות הקוד, כולל: