איך קובעים פגישות ב-Google Chat

רמת תכנות: רמה בינונית
משך: 25 דקות
סוג הפרויקט: אפליקציית Google Chat

מטרות

• להבין מה הפתרון עושה.
• להבין מה שירותי Apps Script עושים במסגרת לפתרון הבעיה.
• מגדירים את הסביבה.
• מגדירים את הסקריפט.
• מריצים את הסקריפט.

מידע על הפתרון הזה

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

איך זה עובד

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

שירותי Apps Script

הפתרון הזה משתמש בשירותים הבאים:

• שירות יומן – יוצר את אירוע ביומן מפרטי הפגישה שסיפקתם.
• שירות בסיס – נעשה שימוש במחלקה Session כדי לקבל אזור הזמן של הסקריפט. יומן Google משתמש באזור הזמן הזה כאשר תזמון האירוע.
• שירות תשתיות – עיצוב התאריך עבור האירוע ביומן מקודד ומזהה את האירוע כדי לקבל את כתובת ה-URL של האירוע.

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

כדי להשתמש בדוגמה הזו, צריך לעמוד בדרישות המוקדמות הבאות:

• חשבון Google (חשבונות Google Workspace יכולים נדרש אישור של האדמין).
• דפדפן אינטרנט עם גישה לאינטרנט.
• פרויקט ב-Google Cloud.

הגדרת הסביבה

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

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

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

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

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

הפעלת ה-API

לפני שמשתמשים ב-Google APIs, צריך להפעיל אותם בפרויקט ב-Google Cloud. אפשר להפעיל ממשק API אחד או יותר בפרויקט אחד ב-Google Cloud.

• בפרויקט ב-Cloud, מפעילים את Google Chat API.

  הפעלת ה-API

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

בכל האפליקציות ל-Chat צריך להגדיר את מסך ההסכמה. מתבצעת הגדרה מסך ההסכמה ל-OAuth של האפליקציה שלך מגדיר מה Google מציגה למשתמשים רושם את האפליקציה כדי שתוכל לפרסם אותה מאוחר יותר.

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

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

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

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

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

הגדרת הסקריפט

יצירת פרויקט Apps Script

1. לוחצים על הלחצן הבא כדי לפתוח את קביעת פגישות מ-Google Chat. פרויקט Apps Script.
   פתיחת הפרויקט
2. לוחצים על סקירה כללית .
3. בדף הסקירה הכללית, לוחצים על 'יצירת עותק' .

העתקת מספר הפרויקט ב-Cloud

1. במסוף Google Cloud, נכנסים לתפריט > IAM & אדמין > הגדרות.

   כניסה לדף IAM & הגדרות אדמין

2. מעתיקים את הערך בשדה Project number.

הגדרת פרויקט Cloud של פרויקט Apps Script

1. בפרויקט Apps Script שהעתקתם, לוחצים על Project Settings (הגדרות הפרויקט) .
2. בקטע פרויקט ב-Google Cloud Platform (GCP), לוחצים על שינוי פרויקט.
3. בקטע מספר הפרויקט ב-GCP, מדביקים את מספר הפרויקט ב-Google Cloud.
4. לוחצים על Set project.

יצירת פריסה לבדיקה

1. בפרויקט Apps Script שהעתקתם, לוחצים על Deploy (פריסה) > בדיקת פריסות.
2. מעתיקים את מזהה הפריסה הראשית לשימוש בשלב מאוחר יותר, ולוחצים על סיום.

הגדרה של Chat API

1. נכנסים לדף Chat API במסוף Google Cloud.
   כניסה ל-Chat API
2. לוחצים על Configuration.
3. מגדירים את Chat API באמצעות הפרטים הבאים:
   • שם: Meeting Scheduler
   • כתובת URL של הדמות: מוסיפים כתובת URL שמפנה לתמונה בגודל מינימלי של 256x256 פיקסלים.
   • תיאור: Quickly create meetings.
   • פונקציונליות: מסמנים את שתי התיבות כדי לאפשר למשתמשים לשלוח הודעות ישירות לאפליקציה. ולהוסיף אותה למרחבים משותפים.
   • הגדרות חיבור: לוחצים על Apps Script ומזינים את מזהה פריסת ראש.
   • פקודות לסגירת פקודות: הוספת פקודות דרך שורת הפקודות /help ו-/schedule_Meeting על ידי ביצוע השלבים הבאים:
     1. לוחצים על הוספת פקודה של שורת הבלוכסן ומגדירים אותה באמצעות הקוד הבא מידע:
        • שם: /help
        • מזהה הפקודה: 1
        • תיאור: Learn what this app does.
     2. לוחצים שוב על הוספת פקודה של שורת הבלוכסן ומגדירים אותה באמצעות הקוד הבא מידע:
        • שם: /schedule_Meeting
        • מזהה הפקודה: 2
        • תיאור: Schedule a meeting.
        • מסמנים את התיבה פתיחה של תיבת דו-שיח.
   • הרשאות: בוחרים באפשרות אנשים וקבוצות ספציפיים בדומיין. מזינים את כתובת האימייל.
4. לוחצים על שמירה ומרעננים את הדף.
5. בדף ההגדרות האישיות, בקטע סטטוס האפליקציה, מגדירים את הסטטוס. לפעיל - זמין למשתמשים.
6. לוחצים על שמירה.

מריצים את הסקריפט

1. פותחים את Google Chat.
2. לוחצים על הסמל 'התחלת צ'אט' .
3. מחפשים את שם האפליקציה, Meeting Scheduler.
4. צריך לשלוח הודעה ראשונית, למשל hello, כדי לבקש הרשאה.

5. כשהאפליקציה מגיבה, לוחצים על הגדרה ומאשרים את האפליקציה. אם במסך ההסכמה של OAuth מוצגת האזהרה האפליקציה הזו לא מאומתת כדי להמשיך, בוחרים באפשרות מתקדם >. עוברים אל {Project Name} (לא בטוח).

6. שולחים את המספר /schedule_Meeting לאפליקציה.

7. בתיבת הדו-שיח, מוסיפים לפחות כתובת אימייל אחת של המוזמן. אפשר לעדכן את בשדות אחרים או להשתמש ברשומות ברירת המחדל.

8. לוחצים על שליחה.

9. כדי לפתוח את הפגישה, לוחצים על פתיחת האירוע ביומן.

בדיקת הקוד

כדי לבדוק את קוד Apps Script של הפתרון הזה, לוחצים על הצגת קוד המקור בהמשך:

הצגת קוד המקור

Code.gs

solutions/schedule-meetings/Code.js

הצגת הקוד ב-GitHub

// To learn how to use this script, refer to the documentation:
// https://developers.google.com/apps-script/samples/chat-apps/schedule-meetings

/*
Copyright 2022 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

// Application constants
const APPNAME = 'Chat Meeting Scheduler';
const SLASHCOMMAND = {
  HELP: 1, // /help
  DIALOG: 2, // /schedule_Meeting
};

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * Called when the Chat app is added to a space. The Chat app can either be directly added to the space
 * or added by a @mention. If the Chat app is added by a @mention, the event object includes a message property. 
 * Returns a Message object, which is usually a welcome message informing users about the Chat app.
 *
 * @param {Object} event The event object from Google Chat
 */
function onAddToSpace(event) {
  let message = '';

  // Personalizes the message depending on how the Chat app is called.
  if (event.space.singleUserBotDm) {
    message = `Hi ${event.user.displayName}!`;
  } else {
    const spaceName = event.space.displayName ? event.space.displayName : "this chat";
    message = `Hi! Thank you for adding me to ${spaceName}`;
  }

  // Lets users know what they can do and how they can get help.
  message = message + '/nI can quickly schedule a meeting for you with just a few clicks.' +
    'Try me out by typing */schedule_Meeting*. ' +
    '/nTo learn what else I can do, type */help*.'

  return { "text": message };
}

/**
 * Responds to a MESSAGE event triggered in Chat.
 * Called when the Chat app is already in the space and the user invokes it via @mention or / command.
 * Returns a message object containing the Chat app's response. For this Chat app, the response is either the
 * help text or the dialog to schedule a meeting.
 * 
 * @param {object} event The event object from Google Chat
 * @return {object} JSON-formatted response as text or Card message
 */
function onMessage(event) {

  // Handles regular onMessage logic.
  // Evaluates if and handles for all slash commands.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {

      case SLASHCOMMAND.DIALOG: // Displays meeting dialog for /schedule_Meeting.

        // TODO update this with your own logic to set meeting recipients, subjects, etc (e.g. a group email).
        return getInputFormAsDialog_({
          invitee: '',
          startTime: getTopOfHourDateString_(),
          duration: 30,
          subject: 'Status Stand-up',
          body: 'Scheduling a quick status stand-up meeting.'
        });

      case SLASHCOMMAND.HELP: // Responds with help text for /help.
        return getHelpTextResponse_();

      /* TODO Add other use cases here. E.g:
      case SLASHCOMMAND.NEW_FEATURE:  // Your Feature Here
        getDialogForAddContact(message);
      */

    }
  }
  else {
    // Returns text if users didn't invoke a slash command.
    return { text: 'No action taken - use Slash Commands.' }
  }
}

/**
 * Responds to a CARD_CLICKED event triggered in Chat.
 * @param {object} event the event object from Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/chat/api/guides/message-formats/events
 */
function onCardClick(event) {
  if (event.action.actionMethodName === 'handleFormSubmit') {
    const recipients = getFieldValue_(event.common.formInputs, 'email');
    const subject = getFieldValue_(event.common.formInputs, 'subject');
    const body = getFieldValue_(event.common.formInputs, 'body');

    // Assumes dialog card inputs for date and times are in the correct format. mm/dd/yyy HH:MM
    const dateTimeInput = getFieldValue_(event.common.formInputs, 'date');
    const startTime = getStartTimeAsDateObject_(dateTimeInput);
    const duration = Number(getFieldValue_(event.common.formInputs, 'duration'));

    // Handles instances of missing or invalid input parameters.
    const errors = [];

    if (!recipients) {
      errors.push('Missing or invalid recipient email address.');
    }
    if (!subject) {
      errors.push('Missing subject line.');
    }
    if (!body) {
      errors.push('Missing event description.');
    }
    if (!startTime) {
      errors.push('Missing or invalid start time.');
    }
    if (!duration || isNaN(duration)) {
      errors.push('Missing or invalid duration');
    }
    if (errors.length) {
      // Redisplays the form if missing or invalid inputs exist.
      return getInputFormAsDialog_({
        errors,
        invitee: recipients,
        startTime: dateTimeInput,
        duration,
        subject,
        body
      });
    }

    //  Calculates the end time via duration.
    const endTime = new Date(startTime.valueOf());
    endTime.setMinutes(endTime.getMinutes() + duration);

    // Creates calendar event with notification.
    const calendar = CalendarApp.getDefaultCalendar()
    const scheduledEvent = calendar.createEvent(subject,
      startTime,
      endTime,
      {
        guests: recipients,
        sendInvites: true,
        description: body + '\nThis meeting scheduled by a Google Chat App!'
      });

    // Gets a link to the Calendar event.
    const url = getCalendarEventURL_(scheduledEvent, calendar)

    return getConfirmationDialog_(url);

  } else if (event.action.actionMethodName === 'closeDialog') {

    // Returns this dialog as success.
    return {
      actionResponse: {
        type: 'DIALOG',
        dialog_action: {
          actionStatus: 'OK'
        }
      }
    }
  }
}

/**
 * Responds with help text about this Chat app.
 * @return {string} The help text as seen below
 */
function getHelpTextResponse_() {
  const help = `*${APPNAME}* lets you quickly create meetings from Google Chat. Here\'s a list of all its commands:
  \`/schedule_Meeting\`  Opens a dialog with editable, preset parameters to create a meeting event
  \`/help\`  Displays this help message

  Learn more about creating Google Chat apps at https://developers.google.com/chat.`

  return { 'text': help }
}

Dialog.gs

solutions/schedule-meetings/Dialog.js

הצגת הקוד ב-GitHub

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
* Form input dialog as JSON.
* @return {object} JSON-formatted cards for the dialog.
*/
function getInputFormAsDialog_(options) {
  const form = getForm_(options);
  return {
    'actionResponse': {
      'type': 'DIALOG',
      'dialogAction': {
        'dialog': {
          'body': form
        }
      }
    }
  };
}

/**
* Form JSON to collect inputs regarding the meeting.
* @return {object} JSON-formatted cards.
*/
function getForm_(options) {
  const sections = [];

  // If errors present, display additional section with validation messages.
  if (options.errors && options.errors.length) {
    let errors = options.errors.reduce((str, err) => `${str}• ${err}<br>`, '');
    errors = `<b>Errors:</b><br><font color="#ba0000">${errors}</font>`;
    const errorSection = {
      'widgets': [
        {
          textParagraph: {
            text: errors
          }
        }
      ]
    }
    sections.push(errorSection);
  }
  let formSection = {
    'header': 'Schedule meeting and send email to invited participants',
    'widgets': [
      {
        'textInput': {
          'label': 'Event Title',
          'type': 'SINGLE_LINE',
          'name': 'subject',
          'value': options.subject
        }
      },
      {
        'textInput': {
          'label': 'Invitee Email Address',
          'type': 'SINGLE_LINE',
          'name': 'email',
          'value': options.invitee,
          'hintText': 'Add team group email'
        }
      },
      {
        'textInput': {
          'label': 'Description',
          'type': 'MULTIPLE_LINE',
          'name': 'body',
          'value': options.body
        }
      },
      {
        'textInput': {
          'label': 'Meeting start date & time',
          'type': 'SINGLE_LINE',
          'name': 'date',
          'value': options.startTime,
          'hintText': 'mm/dd/yyyy H:MM'
        }
      },
      {
        'selectionInput': {
          'type': 'DROPDOWN',
          'label': 'Meeting Duration',
          'name': 'duration',
          'items': [
            {
              'text': '15 minutes',
              'value': '15',
              'selected': options.duration === 15
            },
            {
              'text': '30 minutes',
              'value': '30',
              'selected': options.duration === 30
            },
            {
              'text': '45 minutes',
              'value': '45',
              'selected': options.duration === 45
            },
            {
              'text': '1 Hour',
              'value': '60',
              'selected': options.duration === 60
            },
            {
              'text': '1.5 Hours',
              'value': '90',
              'selected': options.duration === 90
            },
            {
              'text': '2 Hours',
              'value': '120',
              'selected': options.duration === 120
            }
          ]
        }
      }
    ],
    'collapsible': false
  };
  sections.push(formSection);
  const card =  {
    'sections': sections,
    'name': 'Google Chat Scheduled Meeting',
    'fixedFooter': {
      'primaryButton': {
        'text': 'Submit',
        'onClick': {
          'action': {
            'function': 'handleFormSubmit'
          }
        },
        'altText': 'Submit'
      }
    }
  };
  return card;
}

/**
* Confirmation dialog after a calendar event is created successfully.
* @param {string} url The Google Calendar Event url for link button
* @return {object} JSON-formatted cards for the dialog
*/
function getConfirmationDialog_(url) {
  return {
    'actionResponse': {
      'type': 'DIALOG',
      'dialogAction': {
        'dialog': {
          'body': {
            'sections': [
              {
                'widgets': [
                  {
                    'textParagraph': {
                      'text': 'Meeting created successfully!'
                    },
                    'horizontalAlignment': 'CENTER'
                  },
                  {
                    'buttonList': {
                      'buttons': [
                        {
                          'text': 'Open Calendar Event',
                          'onClick': {
                            'openLink': {
                              'url': url
                            }
                          }
                        }

                      ]
                    },
                    'horizontalAlignment': 'CENTER'
                  }
                ]
              }
            ],
            'fixedFooter': {
              'primaryButton': {
                'text': 'OK',
                'onClick': {
                  'action': {
                    'function': 'closeDialog'
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Utilities.gs

solutions/schedule-meetings/Utilities.js

הצגת הקוד ב-GitHub

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
* Helper function that gets the field value from the given form input.
* @return {string} 
*/
function getFieldValue_(formInputs, fieldName) {
  return formInputs[fieldName][''].stringInputs.value[0];
}

// Regular expression to validate the date/time input.
const DATE_TIME_PATTERN = /\d{1,2}\/\d{1,2}\/\d{4}\s+\d{1,2}:\d\d/;

/**
* Casts date and time from string to Date object.
* @return {date} 
*/
function getStartTimeAsDateObject_(dateTimeStr) {
  if (!dateTimeStr || !dateTimeStr.match(DATE_TIME_PATTERN)) {
    return null;
  }

  const parts = dateTimeStr.split(' ');
  const [month, day, year] = parts[0].split('/').map(Number);
  const [hour, minute] = parts[1].split(':').map(Number);


  Session.getScriptTimeZone()

  return new Date(year, month - 1, day, hour, minute)
}

/** 
* Gets the current date and time for the upcoming top of the hour (e.g. 01/25/2022 18:00).
* @return {string} date/time in mm/dd/yyy HH:MM format needed for use by Calendar
*/
function getTopOfHourDateString_() {
  const date = new Date();
  date.setHours(date.getHours() + 1);
  date.setMinutes(0, 0, 0);
  // Adding the date as string might lead to an incorrect response due to time zone adjustments.
  return Utilities.formatDate(date, Session.getScriptTimeZone(), 'MM/dd/yyyy H:mm');
}


/** 
* Creates the URL for the Google Calendar event.
*
* @param {object} event The Google Calendar Event instance
* @param {object} cal The associated Google Calendar 
* @return {string} URL in the form of 'https://www.google.com/calendar/event?eid={event-id}'
*/
function getCalendarEventURL_(event, cal) {
  const baseCalUrl = 'https://www.google.com/calendar';
  // Joins Calendar Event Id with Calendar Id, then base64 encode to derive the event URL.
  let encodedId = Utilities.base64Encode(event.getId().split('@')[0] + " " + cal.getId()).replace(/\=/g, '');
  encodedId = `/event?eid=${encodedId}`;
  return (baseCalUrl + encodedId);

}

תורמים

הדוגמה הזו מתוחזקת על ידי Google בעזרת מומחי המפתחים של Google.

השלבים הבאים

• סקירה כללית למפתחי צ'אט
• איך מפתחים אפליקציות ל-Google Chat באמצעות Apps Script