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

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

בשיעור ה-Lab הזה תלמדו על תהליך עבודה מודרני מבוסס-AI ליצירת תוסף דינמי ל-Gmail מאפס. תשתמשו ב-Gemini CLI כדי לתזמן סביבת פיתוח מקומית עוצמתית, תוך שימוש בשרתי MCP (פרוטוקול הקשר של המודל) ובתוספים של 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. הגדרה ודרישות

לפני שמתחילים את שיעור ה-Lab

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

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

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

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

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

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

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

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

במשימה הזו תגדירו את Gemini CLI ואת התוספים שלו כדי לנהל את פרויקטי הענן ואת פרויקטי 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 כדי ליצור תוסף ל-Gmail.

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

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

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