פיתוח תוסף ל-Google Workspace באמצעות Node.js

ליצור תוספים ל-Google Workspace ב-Cloud Functions באמצעות זמן הריצה של Node.js שפועל ב-Gmail, ב-Google Drive, ביומן Google, ב-Google Docs, ב-Google Sheets וב-Google Slides.

מטרות

• מגדירים את הסביבה.
• יוצרים ופורסים פונקציה של Cloud Functions.
• יוצרים את התוסף ופורסים אותו.
• מתקינים את התוסף.

דרישות מוקדמות

• פרויקט ב-Google Cloud.

• מוודאים שהפעלתם את החיוב בפרויקט שלכם ב-Cloud. איך בודקים את סטטוס החיוב של הפרויקטים

• ‫Cloud SDK מוגדר עם פרויקט Cloud.

הגדרת הסביבה

פותחים את פרויקט Cloud במסוף Google Cloud

1. נכנסים לדף Select a project במסוף Google Cloud.

   בוחרים פרויקט ב-Cloud

2. בוחרים את הפרויקט ב-Google Cloud שבו רוצים להשתמש. לחלופין, לוחצים על Create project ופועלים לפי ההוראות במסך. אם יוצרים פרויקט ב-Google Cloud, יכול להיות שיהיה צורך להפעיל את החיוב בפרויקט.

מגדירים את מסך ההסכמה של OAuth

כדי להשתמש בתוספים ל-Google Workspace, צריך להגדיר מסך הסכמה. הגדרת מסך ההסכמה ל-OAuth של התוסף קובעת מה Google מציגה למשתמשים.

1. במסוף Google Cloud, עוברים אל תפריט menu > Google Auth platform > Branding.

   מעבר לדף Branding

2. אם כבר הגדרתם את Google Auth platform, אתם יכולים לקבוע את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטעים Branding,‏ Audience וData Access. אם מופיעה ההודעה Google Auth platform not configured yet, לוחצים על Get Started:
1. בקטע App Information בשדה App name, מזינים שם לאפליקציה.
2. בקטע User support email, בוחרים כתובת אימייל לתמיכה שאליה משתמשים יפנו אם יש להם שאלות לגבי ההסכמה שלהם.
3. לוחצים על Next.
4. בקטע Audience, לוחצים על Internal.
5. לוחצים על Next.
6. בקטע Contact Information, מזינים כתובת אימייל שאליה אפשר לשלוח התראות על שינויים בפרויקט.
7. לוחצים על Next.
8. בקטע Finish, קוראים את המדיניות של Google בנושא נתוני משתמשים בשירותי API. אם אתם מסכימים, מסמנים את התיבה I agree to the Google API Services: User Data Policy.
9. לוחצים על Continue.
10. לוחצים על Create.
3. כרגע אתם יכולים לדלג על הוספת היקפי הרשאות. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ לארגון שלכם ב-Google Workspace, תצטרכו לשנות את סוג המשתמש ל-External. לאחר מכן מוסיפים את היקפי ההרשאות שהאפליקציה דורשת. למידע נוסף, אפשר לעיין במדריך המלא בנושא הגדרת הסכמה ל-OAuth.

יצירה ופריסה של פונקציה של Cloud Functions

1. במסוף Google Cloud, לוחצים על Activate Cloud Shell .

   הפעלת Cloud Shell

   הטרמינל של Cloud Shell ייפתח ויתחיל סשן בחלונית התחתונה של מסוף Google Cloud.

2. לוחצים על Authorize כדי להקצות משאבים ולהתחבר ל-Cloud Shell.

3. במסוף Cloud Shell, מפעילים את Cloud Functions API, את Cloud Build API, את Google Workspace Add-ons API ואת Compute Engine API:

   gcloud services enable cloudfunctions.googleapis.com  \
                       cloudbuild.googleapis.com  \
                       gsuiteaddons.googleapis.com  \
                       compute.googleapis.com
   

4. כדי לפתוח את Cloud Shell Editor, לוחצים על Open Editor בסרגל הכלים שבחלון של Cloud Shell.

   עורך הקוד המובנה הזה מאפשר לכם לראות ולערוך קבצים באותה סביבה שבה הפרויקטים נבנים ונפרסים.

5. בתיקייה הריקה, יוצרים את הקובץ function.js עם קוד הדוגמה הבא:

   /**
    * Cloud Function that loads the homepage for a
    * Google Workspace add-on.
    *
    * @param {Object} req Request sent from Google
    * @param {Object} res Response to send back
    */
   exports.loadHomePage = function addonsHomePage (req, res) {
     res.send(createAction());
   };
   
   /** Creates a card with two widgets. */
   function createAction() {
     return {
       "action": {
         "navigations": [
           {
             "pushCard": {
               "header": {
                 "title": "Cats!"
               },
               "sections": [
                 {
                   "widgets": [
                     {
                       "textParagraph": {
                         "text": "Your random cat:"
                       }
                     },
                     {
                       "image": {
                         "imageUrl": "https://cataas.com/cat"
                        }
                     }
                   ]
                 }
               ]
             }
           }
         ]
       }
     };
   }
   

6. באותה תיקייה, יוצרים את הקובץ package.json עם קוד הדוגמה הבא:

   {
     "dependencies": {
       "@google-cloud/functions-framework": "^3.0.0"
     }
   }
   

7. כדי לחזור לטרמינל של Cloud Shell, לוחצים על Open Terminal.

8. מוסיפים את התפקיד Cloud Build Service Account (roles/cloudbuild.builds.builder) לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine.

   קודם כול, מגדירים את ההרשאה לחשבון השירות:

   export PROJECT_ID=$(gcloud config get project)
   export SERVICE_ACCOUNT_NAME=$(gcloud compute project-info describe \
     --format="value(defaultServiceAccount)")
   

   לאחר מכן, מעניקים את ההרשאה החסרה לחשבון השירות:

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
     --role="roles/cloudbuild.builds.builder"
   

9. מריצים את הפקודה הבאה כדי לפרוס את הפונקציה:

   gcloud functions deploy loadHomePage --runtime nodejs22 --trigger-http
   

   אם מתבקשים, מציינים שלא מאפשרים הפעלות לא מאומתות של הפונקציה. יכול להיות שיחלפו כמה דקות עד שהפונקציה תופעל.

יצירת פריסה של תוסף

1. מוצאים את כתובת האימייל של חשבון השירות של התוסף:

   gcloud workspace-add-ons get-authorization
   

2. מקצים לחשבון השירות את התפקיד cloudfunctions.invoker. מחליפים את SERVICE_ACCOUNT_EMAIL בשדה serviceAccountEmail מהשלב הקודם.

   gcloud functions add-iam-policy-binding loadHomePage \
      --role roles/cloudfunctions.invoker \
      --member serviceAccount:SERVICE_ACCOUNT_EMAIL
   

3. מקבלים את כתובת ה-URL של הפונקציה שנפרסה. כדי לקבל את כתובת ה-URL, מריצים את הפקודה הבאה ומחפשים את השדה url בקטע httpsTrigger:

   gcloud functions describe loadHomePage
   

4. כדי לחזור אל Cloud Shell Editor, לוחצים על Open Editor.

5. באותה ספרייה שבה נמצא הקובץ package.json, יוצרים את הקובץ deployment.json עם הקוד לדוגמה הבא. מחליפים את URL ב-url של הפונקציה שנפרסה מהשלב הקודם.

   {
     "oauthScopes": ["https://www.googleapis.com/auth/gmail.addons.execute"],
     "addOns": {
       "common": {
         "name": "My HTTP Add-on",
         "logoUrl": "https://raw.githubusercontent.com/webdog/octicons-png/main/black/beaker.png",
         "homepageTrigger": {
           "runFunction": "URL"
         }
       },
       "gmail": {},
       "drive": {},
       "calendar": {},
       "docs": {},
       "sheets": {},
       "slides": {},
       "httpOptions": {
         "granularOauthPermissionSupport": "OPT_IN"
       }
     }
   }
   

6. חוזרים לטרמינל של Cloud Shell כדי ליצור את הפריסה:

   gcloud workspace-add-ons deployments create quickstart \
      --deployment-file=deployment.json
   

התקנת התוסף

1. מתקינים את הפריסה במצב פיתוח:

   gcloud workspace-add-ons deployments install quickstart
   

2. פותחים את Gmail או טוענים אותו מחדש כדי לראות את התוסף. בסרגל הכלים בצד שמאל, מחפשים את סמל הכימית.

3. לוחצים על הסמל כדי לפתוח את התוסף. אם מוצגת בקשה, מאשרים את התוסף.

אופציונלי: ניקוי

כדי להימנע מחיובים בחשבון, מוחקים את המשאבים שיצרתם:

1. מסירים את התוסף מחשבון Google:

   gcloud workspace-add-ons deployments uninstall quickstart
   

2. כדי להימנע מחיובים על המשאבים שבהם השתמשתם במדריך למתחילים הזה, מוחקים את פרויקט Cloud:

   gcloud projects delete PROJECT_ID
   

   מחליפים את PROJECT_ID במזהה של פרויקט Cloud שבו השתמשתם במדריך למתחילים. מזהה הפרויקט ב-Cloud מופיע בדף לוח הבקרה במסוף Google Cloud.

נושאים קשורים

כדי להוסיף עוד תכונות לתוסף Google Workspace, אפשר לעיין במקורות המידע הבאים:

• איך בונים תוסף ל-Google Workspace באמצעות נקודות קצה של HTTP
• Codelab: Build a Google Workspace add-on with Node.js and Cloud Run
• תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים