‫Apps Script: כתיבת קוד של תוסף ל-Gmail באמצעות Gemini CLI ושרתי MCP

1. סקירה כללית

בשיעור ה-Lab הזה תלמדו איך ליצור תוסף ל-Gmail דינמי מאפס באמצעות תהליך עבודה מודרני מבוסס-AI. תשתמשו ב-Gemini CLI כדי לתזמן סביבת פיתוח מקומית עוצמתית, תוך שימוש בשרתי MCP (Model Context Protocol) ובהרחבות של Gemini CLI כדי לשלב כלים כמו gcloud ו-clasp.

התוסף שתיצרו ייצור תמונה ייחודית של חתול ויציג אותה לפי דרישה, על ידי הפעלת מודל תמונות בפלטפורמת Vertex AI של Google Cloud.

בסיום התהליך, יהיה לכם תוסף ל-Gmail שפועל באופן מלא ומבצע קריאה ל-Vertex AI API כדי ליצור תמונות ייחודיות ישירות בממשק Gmail, והכול מנוהל משורת הפקודה המקומית.

2. מה תלמדו

בסיום שיעור ה-Lab הזה תלמדו איך:

  • איך מגדירים את Gemini CLI ומשתמשים בו עם תוספים
  • יצירת תוסף ל-Gmail שמפעיל API חיצוני
  • שינוי התוסף כדי לקרוא ל-Vertex AI API ליצירת תמונות
  • פריסת גרסת בדיקה של תוסף ל-Google Workspace מממשק המשתמש של Apps Script

3. הגדרה ודרישות

לפני שמתחילים את המעבדה

  1. אם אין לכם חשבון Google, אתם צריכים ליצור חשבון Google. משתמשים בחשבון לשימוש אישי במקום בחשבון לצורכי עבודה או בחשבון בית ספרי. יכול להיות שבחשבונות לצורכי עבודה או בחשבונות בית ספריים יש הגבלות שלא מאפשרות להפעיל את ממשקי ה-API שנדרשים למעבדה הזו.
  2. נכנסים ל-מסוף Google Cloud.
  3. מפעילים את החיוב במסוף Cloud.
  1. יוצרים פרויקט חדש או בוחרים להשתמש בפרויקט קיים.

דרישות לשיעור Lab

כדי להפיק את המרב מה-Lab הזה, תצטרכו:

  • דפדפן אינטרנט: דפדפן אינטרנט רגיל כמו Chrome (מומלץ).
  • זמן מוקדש: חשוב להקדיש מספיק זמן להתמקדות בפעילויות במעבדה.

4. הגדרת הסביבה של Google Cloud

  1. לוחצים על סמל ההפעלה של Cloud Shell 7a0d8a88ebea95af.png: בפינה השמאלית העליונה של הכותרת של המסוף, לוחצים על סמל הטרמינל שמופיע הכיתוב Activate Cloud Shell כשמעבירים מעליו את העכבר.
  2. אישור.
  3. מחכים לאתחול: סשן של Cloud Shell ייפתח במסגרת חדשה בחלק התחתון של חלון המסוף. הסשן יופעל תוך כמה רגעים כי המערכת תספק לכם מכונה וירטואלית (VM) זמנית מבוססת Debian.
  4. אחרי שהסשן יאותחל, תופיע שורת פקודה (user@cloudshell:~ $).
  5. ניתן להרחיב את חלון Cloud Shell על ידי לחיצה על לחצן ההרחבה כדי להגדיל את גודל החלון.
  6. מאמתים את הפרויקט: מריצים את הפקודה:
gcloud config list project
  1. שינוי הפרויקט (אם צריך):
gcloud config set project [YOUR_PROJECT_ID]

הכול מוכן, אפשר להתחיל את הפעילויות במעבדה.

5. הגדרת סביבת הפיתוח המקומית

במשימה הזו תגדירו את Gemini CLI ואת התוספים שלו כדי לנהל את הפרויקטים שלכם ב-Cloud וב-Apps Script מהטרמינל.

  1. ‫Gemini CLI כבר מותקן כחלק מסביבת Cloud Shell, כך שאין צורך להתקין אותו.
  2. ‫clasp כבר מותקן כחלק מסביבת Cloud Shell, אבל אנחנו נוודא שאנחנו משתמשים בגרסה העדכנית ביותר במעבדה הזו.
npm install -g @google/clasp@latest
  1. כדי לתת הרשאה ל-clasp לגשת לחשבון שלכם, מזינים את הפקודה הבאה ופועלים לפי ההוראות שבהמשך:
clasp login --no-localhost

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

db77651c2ce19d7f.png

מעתיקים את כתובת ה-URL מחלון הדפדפן (שמתחילה ב-http://localhost:8888/?code=xxx), מדביקים אותה בסשן הפתוח של Cloud Shell ולוחצים על Enter. ‫clasp ימשיך את תהליך ההרשאה, ואם הכניסה תצליח, תופיע הודעת אישור כמו You are logged in as user@gmail.com.

  1. מתקינים את התוספים ל-Gemini CLI של clasp.
gemini extensions install https://github.com/google/clasp --consent
  1. מתקינים gcloud תוספים ל-Gemini CLI.
gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent
  1. מתקינים תוספים ל-Gemini CLI למפתחים של Google Workspace.
gemini extensions install https://github.com/googleworkspace/developer-tools --consent
  1. יוצרים ספריית פרויקט ריקה:
mkdir genai-cat-add-on
  1. עוברים לספריית הפרויקט החדשה שיצרתם:
cd genai-cat-add-on
  1. מגדירים את קובץ ההקשר של Gemini CLI לפרויקט הזה:
cat << 'END_OF_FILE' > GEMINI.md
## **Gemini CLI Instructions for Gmail Add-on Development**

You are a methodical **Google Workspace extensibility and integration expert**. Your goal is to build a Gmail Add-on for the `genai-cat-add-on` project by writing Apps Script code and using command-line tools.

---

## **Tools Available**

*   **`clasp`**: Use this tool for all Apps Script project operations like pushing files.
*   **`gcloud`**: Use this tool for Google Cloud operations, such as enabling APIs or managing IAM permissions.
*   **`workspace-developer`**: Use this tool to search the official Google Workspace documentation for correct syntax, manifest properties, and required OAuth scopes.

---

## **Development Workflow and Validation**

You MUST follow the workflow below when building the add-on:

1.  **Mandatory Documentation Check**: Before creating, committing, or modifying any code (especially manifest files or Apps Script functions), you **MUST** first utilize the **`workspace-developer` tool** and use **search_workspace_docs** to search and validate the necessary Apps Script syntax, OAuth scopes, Apps Script services such as GmailApp, and best practices. Always refer to the official Google Workspace developer documentation via this tool for authoritative information.
2.  **Security and Scopes**: For every code commit or structural change, you must first **verify the manifest file (`appsscript.json`) includes the necessary OAuth scopes** for Gmail access and external API calls, ensuring you use the **minimal required scopes** and nothing more to adhere to the principle of least privilege.
3.  **Versioning/Persistence**: After any successful file creation, update, or deletion, you must ensure the changes are persistently saved and pushed using the appropriate `clasp` tool command.
4.  **Error Handling**: Include appropriate debugging and robust error handling code in all Apps Script functions.

---

## **Project and API Specifications**

* **Project Focus:** All work is centered on the **`genai-cat-add-on`** Apps Script project.
* **Vertex AI Details:** If asked to generate images, you must use the **`gemini-2.5-flash-image`** model on **Vertex AI**. Do NOT use imagen. All Vertex AI operations must use the currently logged-in user's credentials and the current Google Cloud project.
END_OF_FILE
  1. מפעילים את Google Apps Script API בחשבון המעבדה של התלמיד, לוחצים על Google Apps Script API ומעבירים את המתג ממצב Off (מושבת) למצב On (מופעל).

41eb25a89e13e1ff.gif

6. התחלה ואימות של הגדרת Gemini CLI

  1. מפעילים את Gemini בספריית הפרויקט.
gemini
  1. כברירת מחדל, Gemini CLI יבקש מכם לבדוק ולאשר שינויים בקבצים. במעבדה הזו, מומלץ להשבית את האפשרות הזו על ידי הקשה על Shift + Tab כדי לאשר את העריכות באופן אוטומטי, וכך לסיים את המעבדה בזמן. האפשרות הזו אמורה להיות מודגשת באדום במסך.

31a7326896719d73.png

  1. בודקים שהקובץ GEMINI.md נטען ומציגים את מה שנטען בהקשר של Gemini CLI:
/memory show
  1. מוודאים ששרתי ה-MCP מוגדרים בצורה נכונה. יכול להיות שייקח זמן עד ששרת ה-MCP של gcloud יאותחל, אז אל תיבהלו אם הוא מופיע כמנותק. מחכים כמה דקות ומנסים שוב.
/mcp list

7. יצירת תוסף ל-Gmail

  1. מבקשים מ-Gemini ליצור את הגרסה הראשונה של תוסף ל-Gmail:
Use Apps Script to create a new Google Workspace add-on that displays a random cat image using the Cat-as-a-Service API upon opening the add-on in Gmail. Make sure you update the code and manifest files, use the correct scopes, and use the API documentation at https://cataas.com/doc.html.

Once done, provide a link to view the project.
  1. אחרי ש-Gemini מסיים להגיב להנחיה, לוחצים על הקישור שמופיע או עוברים לדף הבית של Apps Script ולוחצים על פרויקט genai-cat-add-on.
  2. בצד ימין של הדף, לוחצים על סמל הגדרות הפרויקט (סמל גלגל השיניים) 9485fddc5bf46369.png.

2bc043bb3c3a216d.png

  1. בוחרים באפשרות הצגת קובץ המניפסט 'appsscript.json' בעורך.

e74dca570d64e540.png 9. עוברים למסך העורך ומעיינים בקוד שנוצר בקובץ `Code.gs` ובקובץ המניפסט שמגדיר את הפרויקט בקובץ `appsscript.json`

8. התקנה ובדיקה של התוסף

  1. חוזרים לדף הפרויקט של Apps Script.
  2. מחפשים את הלחצן Deploy (פריסה) בחלק העליון.
  3. לוחצים על החץ לצד 'פריסה' ובוחרים באפשרות פריסות לבדיקה.
  4. בתיבת הדו-שיח 'בדיקת פריסות' שמופיעה, אמורה להיות אפשרות להתקין את התוסף שלא פורסם.
  5. לוחצים על הלחצן התקנה.
  6. תופיע הודעת אישור. בתחתית, לוחצים על Done (סיום) כדי לסגור את תיבת הדו-שיח של הפריסה.
  7. פותחים את דף הבית של Gmail ומרעננים אותו.
  8. התוסף אמור להיות זמין עכשיו. התוסף יופיע בחלונית הצד משמאל.
  9. בפעם הראשונה שתשתמשו בתוסף, תתבקשו לאשר לו גישה לנתונים או להרשאות הנדרשים. פועלים לפי ההנחיות שעל המסך כדי לתת הרשאות.
  10. אמורה להופיע תמונה של חתול. אם היא לא מופיעה, אפשר לשתף את הודעת השגיאה עם Gemini CLI כדי לקבל עזרה בפתרון הבעיה.

9. הטמעה של הלוגיקה של יצירת תמונות באמצעות AI

  1. מבקשים מ-Gemini להוסיף עכשיו לוגיקה ליצירת תמונה:
Now update the add-on to display an AI-generated image using the samples in https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-generation#use-image-generation. 

The image should show a cute cat if I open my inbox, and should add a speech bubble saying "<email sender name> rocks!" with the actual sender name when I open an email.
  1. מרעננים את דף הבית של Gmail ופותחים את התוסף שוב. אם מתבקשים, מאשרים את ההרשאות החדשות.
  2. עכשיו אמורה להופיע תמונה של חתול שנוצרה על ידי AI. אם תמונה לא מוצגת, אפשר לפתור את הבעיה באמצעות Gemini CLI. לשם כך, משתפים את הודעת השגיאה ופועלים לפי ההוראות שבה.
  3. פותחים אימייל ורואים איך התמונה משתנה ומציגה בועת דיבור עם שם השולח. פותרים בעיות ב-Gemini CLI באופן דומה לשלב הקודם.

10. [אופציונלי] הוספת תפריט נפתח לבחירת סוג בעל החיים

  1. מבקשים מ-Gemini להוסיף את האפשרות ליצור תמונות של חיות אחרות בנוסף לתמונה של החתול.
Add a dropdown menu that lets the user choose the type of animal image it wants. Choose 2 random animals to add to the list in addition to the cat image.
  1. כדי לרענן את התוסף, לוחצים על סמל האפשרויות הנוספות (שלוש הנקודות האנכיות) ואז על 'רענון', או מרעננים את דף הבית של Gmail ופותחים שוב את התוסף.
  2. כדי לבדוק את הפונקציונליות החדשה, בוחרים תמונה אחרת של חיה. אם יש שגיאות, כמו ממשק משתמש שלא מתעדכן או שגיאה שמופיעה, אפשר לפתור את הבעיות באמצעות Gemini CLI. לשם כך, משתפים את הודעת השגיאה ופועלים לפי ההוראות שמופיעות בה.

11. הסרת המשאבים

יציאה מ-Gemini CLI

כדי לצאת מ-Gemini CLI ולראות את סטטיסטיקות השימוש, מריצים את הפקודה הבאה:

/quit

מחיקת פרויקט בענן ב-Google Cloud

כדי להימנע מחיובים בחשבון Google Cloud על המשאבים שבהם השתמשתם ב-Codelab הזה, מומלץ למחוק את הפרויקט בענן ב-Google Cloud.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

מחיקת פרויקט Apps Script

לוחצים על סמל המידע dc2524b2c9878567.png בחלונית הניווט הימנית, ואז על סמל האשפה 4ad389ddfeda5d7f.png בצד השמאלי של המסך כדי להסיר את פרויקט Apps Script.

12. טיפים לפתרון בעיות

  • אם נתקלתם בבעיות ב-Gemini CLI ובתוספים, אתם יכולים להשתמש בפקודה הבאה כדי להריץ גרסה ספציפית של Gemini CLI:
npx https://github.com/google-gemini/gemini-cli#v0.12.0
  • אם נתקלים בשגיאות, אפשר לבקש מ-Gemini לתקן אותן ולשתף את השגיאות ואת ההקשר (איפה השגיאה מתרחשת).
  • אם Gemini מיישם רישום שגיאות ומבקש לשתף שגיאות, מריצים מחדש את השלבים שגרמו לשגיאה ואז משתפים את התוצאות עם Gemini.
  • אפשר לנסות הנחיה כמו:
You have my permission to fix any errors. Please go ahead and make it work.
  • אם נתקעתם ואתם רוצים לעזור ל-Gemini, אתם יכולים להשתמש בהנחיה הבאה:
Use the following Github repo as a reference implementation to make my add-on work: https://github.com/googleworkspace/add-ons-samples/tree/main/apps-script/generative-ai/cat-add-on

13. מעולה!

השלמתם בהצלחה את המעבדה והשתמשתם ב-Gemini CLI כדי לתכנת בשיטת Vibe coding תוסף ל-Gmail.

בשיעור ה-Lab הזה למדתם איך:

  • משתמשים ב-Gemini CLI.
  • התקנת כלים והרחבת Gemini CLI באמצעות שרתים של MCP (Model Context Protocol).
  • איך יוצרים תוסף ל-Gmail, פורסים אותו ומתקינים אותו.

עכשיו אתם מוכנים לעבור לשיעור ה-Lab הבא.