בניית תוסף ל-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, נכנסים לתפריט > APIs & Services > מסך ההסכמה של OAuth.

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

  2. בקטע סוג המשתמש, בוחרים באפשרות פנימי ולוחצים על יצירה.
  3. ממלאים את טופס הרישום של האפליקציה ולוחצים על שמירה והמשך.

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

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

יצירה ופריסה של פונקציה ב-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 בדף Dashboard.

השלבים הבאים

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