جلسات را از Google Chat برنامه ریزی کنید

سطح کدنویسی : متوسط
مدت زمان : 25 دقیقه
نوع پروژه : برنامه Google Chat

اهداف

• درک کنید که راه حل چه کاری انجام می دهد.
• آنچه را که سرویس های Apps Script در راه حل انجام می دهند، بدانید.
• محیط خود را تنظیم کنید.
• اسکریپت را تنظیم کنید
• اسکریپت را اجرا کنید.

در مورد این راه حل

از طریق پیام مستقیم (DM) یا فضایی در Google Chat، یک جلسه در تقویم Google برنامه ریزی کنید. می‌توانید جزئیات خاصی را برای جلسه تنظیم کنید، مانند موضوع، زمان شروع، یا مدت، یا از تنظیمات پیش‌فرض برای زمان‌بندی جلسه فوری استفاده کنید.

چگونه کار می کند

اسکریپت برنامه چت از دستورات اسلش و دیالوگ ها برای دریافت جزئیات جلسه از کاربران و برنامه ریزی یک رویداد تقویم استفاده می کند. این اسکریپت شامل تنظیمات جلسه پیش‌فرض است که می‌تواند متناسب با نیازهای شما سفارشی شود.

خدمات اسکریپت برنامه ها

این راه حل از خدمات زیر استفاده می کند:

• سرویس تقویم - رویداد تقویم را از اطلاعات جلسه ارائه شده ایجاد می کند.
• سرویس پایه - از کلاس Session برای بدست آوردن منطقه زمانی اسکریپت استفاده می کند. تقویم هنگام برنامه ریزی رویداد از این منطقه زمانی استفاده می کند.
• سرویس Utilities - تاریخ رویداد تقویم را قالب بندی می کند و شناسه رویداد را برای کمک به دریافت URL رویداد رمزگذاری می کند.

پیش نیازها

• یک حساب Google Workspace تجاری یا سازمانی با دسترسی به Google Chat .
• یک پروژه Google Cloud ایجاد کنید .

محیط خود را تنظیم کنید

پروژه Cloud خود را در کنسول Google Cloud باز کنید

اگر قبلاً باز نشده است، پروژه Cloud را که می‌خواهید برای این نمونه استفاده کنید باز کنید:

1. در کنسول Google Cloud، به صفحه انتخاب پروژه بروید.

   یک پروژه Cloud را انتخاب کنید

2. پروژه Google Cloud را که می خواهید استفاده کنید انتخاب کنید. یا روی ایجاد پروژه کلیک کنید و دستورالعمل های روی صفحه را دنبال کنید. اگر یک پروژه Google Cloud ایجاد می‌کنید، ممکن است لازم باشد صورت‌حساب پروژه را روشن کنید .

API را روشن کنید

قبل از استفاده از Google API، باید آنها را در پروژه Google Cloud روشن کنید. می‌توانید یک یا چند API را در یک پروژه Google Cloud روشن کنید.

• در پروژه Cloud خود، Google Chat API را روشن کنید.

  API را روشن کنید

صفحه رضایت OAuth را پیکربندی کنید

همه برنامه‌های گپ نیاز به پیکربندی صفحه رضایت دارند. پیکربندی صفحه رضایت OAuth برنامه شما را مشخص می کند که Google چه چیزی را برای کاربران نمایش می دهد و برنامه شما را ثبت می کند تا بتوانید بعداً آن را منتشر کنید.

1. در کنسول Google Cloud، به منو > APIs & Services > صفحه رضایت OAuth بروید.

   به صفحه رضایت OAuth بروید

2. برای نوع User Internal را انتخاب کنید، سپس روی Create کلیک کنید.
3. فرم ثبت نام برنامه را تکمیل کنید، سپس روی ذخیره و ادامه کلیک کنید.

4. در حال حاضر، می‌توانید از افزودن دامنه‌ها صرفنظر کنید و روی ذخیره و ادامه کلیک کنید. در آینده، وقتی برنامه‌ای را برای استفاده خارج از سازمان Google Workspace خود ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید و سپس محدوده‌های مجوز مورد نیاز برنامه خود را اضافه کنید.

5. خلاصه ثبت برنامه خود را مرور کنید. برای ایجاد تغییرات، روی ویرایش کلیک کنید. اگر ثبت برنامه خوب به نظر می رسد، روی بازگشت به داشبورد کلیک کنید.

اسکریپت را تنظیم کنید

پروژه Apps Script را ایجاد کنید

1. روی دکمه زیر کلیک کنید تا برنامه زمانبندی جلسات از پروژه Google Chat Apps Script باز شود.
   پروژه را باز کنید
2. روی نمای کلی کلیک کنید.
3. در صفحه نمای کلی، روی Make a copy کلیک کنید .

شماره پروژه Cloud را کپی کنید

1. در کنسول Google Cloud، به منو > IAM & Admin > تنظیمات بروید.

   به تنظیمات IAM و Admin بروید

2. در قسمت Project number مقدار را کپی کنید.

پروژه Cloud پروژه Apps Script را تنظیم کنید

1. در پروژه Apps Script کپی شده خود، روی تنظیمات پروژه کلیک کنید .
2. در پروژه Google Cloud Platform (GCP) ، روی تغییر پروژه کلیک کنید.
3. در شماره پروژه GCP ، شماره پروژه Google Cloud را جای‌گذاری کنید.
4. روی تنظیم پروژه کلیک کنید.

یک استقرار آزمایشی ایجاد کنید

1. در پروژه Apps Script کپی شده خود، روی Deploy > Test Deployments کلیک کنید.
2. شناسه توسعه Head را برای استفاده در مرحله بعد کپی کنید و روی Done کلیک کنید.

Chat API را پیکربندی کنید

1. در کنسول Google Cloud، به صفحه Chat API بروید.
   به Chat API بروید
2. روی پیکربندی کلیک کنید.
3. Chat API را با اطلاعات زیر پیکربندی کنید:
   • نام : Meeting Scheduler
   • نشانی وب آواتار : نشانی اینترنتی اضافه کنید که به تصویری با حداقل اندازه ۲۵۶×۲۵۶ پیکسل اشاره می‌کند.
   • توضیحات : Quickly create meetings.
   • عملکرد : هر دو کادر را علامت بزنید تا به کاربران اجازه دهید مستقیماً به برنامه پیام دهند و آن را به فضاها اضافه کنند.
   • تنظیمات اتصال : روی Apps Script کلیک کنید و شناسه استقرار هد را وارد کنید.
   • دستورات اسلش : ​​با انجام مراحل زیر دستورات اسلش را برای /help و /schedule_Meeting اضافه کنید:
     1. روی دستور Add slash کلیک کنید و آن را با اطلاعات زیر پیکربندی کنید:
        • نام : /help
        • شناسه فرمان : 1
        • توضیحات : Learn what this app does.
     2. دوباره روی دستور Add slash کلیک کنید و آن را با اطلاعات زیر پیکربندی کنید:
        • نام : /schedule_Meeting
        • شناسه فرمان : 2
        • توضیحات : Schedule a meeting.
        • کادر محاوره ای باز می کند را علامت بزنید.
   • مجوزها : افراد و گروه های خاص را در دامنه خود انتخاب کنید و آدرس ایمیل خود را وارد کنید.
4. روی ذخیره کلیک کنید و صفحه را بازخوانی کنید.
5. در صفحه پیکربندی، در زیر وضعیت برنامه ، وضعیت را روی Live - در دسترس کاربران قرار دهید.
6. روی ذخیره کلیک کنید.

اسکریپت را اجرا کنید

1. Google Chat را باز کنید.
2. روی Start a chat کلیک کنید.
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);

}

مراحل بعدی

• نمای کلی توسعه دهنده چت
• با Apps Script یک برنامه Google Chat بسازید