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

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

סקירה כללית

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

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

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

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

(Merchant API) תרשים של עוזר תכנות מבוסס-AI

Merchant API Developer Documentation MCP Server

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

איך זה עובד

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

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

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

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

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

פרומפט של משתמש:

‫"Migrate products.insert code to 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 ואתם צריכים לעדכן אותה. אתם יכולים לשאול על שיטה ספציפית מדור קודם כדי לקבל פרטים על ההטמעה החדשה וקוד לדוגמה רלוונטי.

פרומפט של משתמש:

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

שירות ה-MCP מספק הקשר ממדריכי ההעברה הרשמיים וממסמכי העיון, ומאפשר לעוזר הדיגיטלי להשיב תשובה מפורטת, כולל שם ה-API החדש, accounts.issues.

תרחיש 3: איתור קוד לדוגמה

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

פרומפט של משתמש:

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

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

תרחיש 4: הבנת מושגים שקשורים ל-API

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

פרומפט של משתמש:

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

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

‫"How do I authorize my application calls with Merchant API?‎" (איך מאשרים את הקריאות לאפליקציה באמצעות Merchant API?)

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

תרחיש 5: הסתגלות לשינויים ב-API

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

פרומפט של משתמש:

‫"What is the new way to do a products.custombatch in Merchant API?‎" (מה הדרך החדשה להשתמש ב-products.custombatch ב-Merchant API?)

שירות ה-MCP מאחזר הקשר מתוך Refactor code for concurrent requests (שינוי מבנה הקוד לבקשות מקבילות), ומסביר שאין שיטות custombatch ייעודיות ב-Merchant API. במקום זאת, הוא מספק תיעוד על שימוש ב-HTTP batching עם Content-Type של multipart. העוזר הדיגיטלי יכול להסביר איך ליצור בקשת HTTP אחת שמכילה כמה קריאות ל-API, שנשלחת לנקודת הקצה https://merchantapi.googleapis.com/batch/{sub-api}/v1, ולספק דוגמה לאופן שבו אפשר לבנות את הבקשה מרובת החלקים. כך הופכים משימת העברה שעלולה להיות מבלבלת לתהליך מודרך.

תרחיש 6: תרגום של שאילתת דיווח

אתם יכולים לבקש מהסוכן לתרגם שאילתת דיווח מ-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

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

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

איך זה עובד

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

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

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

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

תחילת העבודה

במסמך Merchant API Agent Skills README מפורטות הוראות שלב אחר שלב בנושאים הבאים:

  • דרישות מוקדמות לשימוש בכלים כמו כלי שורת הפקודה 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?"

‫"Show me a Java example for handling authentication with Merchant API." ‏(הצגת דוגמה ל-Java לטיפול באימות באמצעות Merchant API)

"מוצגת לי הודעת השגיאה '400 הבקשה שגויה' עם שגיאת אימות כשמתקשרים אל productInputs.insert. איך אפשר לפתור את הבעיה?"

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

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

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