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

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

מטרות

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

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

הגדרת הסביבה

פותחים את הפרויקט ב-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, עוברים לתפריט > > Branding.

    כניסה לדף Branding

  2. אם כבר הגדרתם את , תוכלו להגדיר את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטע מיתוג, קהל וגישה לנתונים. אם מופיעה ההודעה not configured yet, לוחצים על Get Started:
    1. בקטע פרטי האפליקציה, בקטע שם האפליקציה, מזינים שם לאפליקציה.
    2. בקטע כתובת אימייל לתמיכה במשתמשים, בוחרים כתובת אימייל לתמיכה שבה המשתמשים יוכלו לפנות אליכם אם יש להם שאלות לגבי ההסכמה שלהם.
    3. לוחצים על הבא.
    4. בקטע קהל, בוחרים באפשרות פנימי.
    5. לוחצים על הבא.
    6. בקטע פרטים ליצירת קשר, מזינים כתובת אימייל שבה תרצו לקבל התראות על שינויים בפרויקט.
    7. לוחצים על הבא.
    8. בקטע סיום, קוראים את המדיניות בנושא נתוני משתמשים בשירותי Google API. אם מסכימים, בוחרים באפשרות אני מסכים/ה למדיניות בנושא נתוני משתמשים בשירותי Google API.
    9. לוחצים על המשך.
    10. לוחצים על יצירה.
  3. בשלב הזה, אפשר לדלג על הוספת היקפי הרשאות. בעתיד, כשיוצרים אפליקציה לשימוש מחוץ לארגון ב-Google Workspace, צריך לשנות את סוג המשתמש לחיצוני. לאחר מכן מוסיפים את היקפי ההרשאה הנדרשים לאפליקציה. למידע נוסף, קראו את המדריך המלא בנושא הגדרת הסכמה ל-OAuth.

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

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

    הפעלת Cloud Shell

    תיפתח חלונית של Cloud Shell Terminal ותופעל סשן בחלונית התחתונה של מסוף 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 Terminal, לוחצים על לחצן ההפעלה של 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 מופיע בדף Dashboard במסוף Google Cloud.

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