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

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

מטרות

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

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

הגדרת הסביבה

פתיחת הפרויקט ב-Cloud במסוף Google Cloud

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

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

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

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

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

  1. במסוף Google Cloud, נכנסים לתפריט > ממשקי API ו- שירותים > מסך ההסכמה של OAuth.

    מעבר למסך ההסכמה ל-OAuth

  2. בקטע סוג המשתמש, בוחרים באפשרות פנימי ולוחצים על יצירה.
  3. ממלאים את טופס הרישום של האפליקציה ולוחצים על שמירה והמשך.
  4. בשלב הזה אפשר לדלג על הוספת היקפי הרשאות וללחוץ על שמירה והמשך. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ ל- בארגון ב-Google Workspace, צריך לשנות את סוג המשתמש לחיצוני, ואז: להוסיף את היקפי ההרשאות שנדרשים לאפליקציה.

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

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

  1. בטרמינל מקומי, מפעילים את Cloud Functions, את Cloud Build ואת Google Workspace Add-ons API:

    gcloud services enable cloudfunctions cloudbuild.googleapis.com gsuiteaddons.googleapis.com
    
  2. בספרייה ריקה, יוצרים את הקובץ 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"
                         }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      };
    }
    
  3. פורסים את הפונקציה:

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

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

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

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

    gcloud workspace-add-ons get-authorization
    
  2. מקצים לחשבון השירות את התפקיד cloudfunctions.invoker:

    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. יוצרים את הקובץ 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": {}
      }
    }
    
  5. יוצרים את הפריסה:

    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: המדריכים הבאים: