۱. مقدمه
برنامههای چت گوگل، سرویسها و منابع را مستقیماً به چت میآورند، جایی که کاربران میتوانند بدون ترک مکالمه، اطلاعات دریافت کنند و اقدامی انجام دهند.
در این آزمایشگاه کد، یاد میگیرید که چگونه یک برنامه چت - "برنامه چت حضور و غیاب" - ایجاد کنید که پاسخگویان تعطیلات را در Gmail تنظیم میکند و جلسات را در Google Calendar زمانبندی میکند. با ساخت برنامه چت حضور و غیاب در Google Apps Script ، میتوانید به راحتی به سایر سرویسهای Google مانند Drive، Gmail، Calendar، Docs، Sheets و موارد دیگر دسترسی داشته باشید.
آنچه یاد خواهید گرفت
- نحوه اضافه کردن کنترلکنندهها در رویدادهای مطرحشده در چت
- نحوه تجزیه اشیاء رویداد ارسال شده از چت
- نحوه پاسخ دادن به چت با پاسخهای قالببندی شده با کارت
- نحوه تعریف و واکنش به اقدامات سفارشی برای کلیک دکمهها در کارتها
آنچه نیاز دارید
- دسترسی به اینترنت و مرورگر وب.
- یک حساب Google Workspace با دسترسی به Google Chat .
- مهارتهای پایه جاوا اسکریپت - Google Apps Script فقط از جاوا اسکریپت پشتیبانی میکند.
۲. کد نمونه را دریافت کنید
برای مشاهده کد هر مرحله در این نمونه، میتوانید یک فایل ZIP دانلود کنید یا مخزن GitHub را کلون کنید.
پوشههای step-NN در مسیر apps-script/attendance-chat-app شامل وضعیت نهایی هر مرحله از این آزمایشگاه کد هستند. آنها برای مرجع در آنجا قرار دارند.
کد را دانلود کنید
برای دانلود کد این codelab، روی دکمه زیر کلیک کنید:
فایل زیپ دانلود شده را از حالت فشرده خارج کنید. این کار یک پوشه اصلی ( google-chat-samples ) را از حالت فشرده خارج میکند که شامل یک پوشه برای هر مرحله از این codelab در apps-script/attendance-chat-app است.
مخزن گیتهاب را کلون کنید
برای کلون کردن مخزن گیتهاب برای این codelab، دستور زیر را اجرا کنید:
git clone https://github.com/googleworkspace/google-chat-samples
۳. ایجاد کنترلکنندهها برای رویدادهای گوگل چت
ایجاد یک پروژه اسکریپت برنامهها
برای ایجاد یک پروژه Apps Script، مراحل زیر را دنبال کنید:
- به script.new بروید.
- روی پروژه بدون عنوان کلیک کنید.
- نام اسکریپت Attendance Chat app را تغییر دهید و روی Rename کلیک کنید.
رویدادها در گوگل چت
بیشتر تعاملات اسکریپت برنامهها با چت، رویدادمحور هستند. تعامل بین کاربر، برنامه چت و چت معمولاً از این ترتیب پیروی میکند:
- کاربر عملی را آغاز میکند، مانند اضافه کردن یک برنامه چت به یک فضا، شروع یک پیام مستقیم (DM) با یک برنامه چت یا حذف یک برنامه چت از یک فضا.
- این اقدام، رویدادی را در برنامهی چت ایجاد میکند که آن را هدف قرار میدهد.
- چت، رویداد مربوطه را که در اسکریپت برنامه چت تعریف شده است، فراخوانی میکند.
چت ۴ رویداد را که برنامه شما میتواند به آنها گوش دهد، فعال میکند:
-
ADDED_TO_SPACE: این رویداد زمانی رخ میدهد که یک کاربر انسانی یک برنامه چت را به یک فضا یا یک پیام مستقیم (DM) اضافه میکند. در Apps Script، شما یک تابعonAddToSpace()برای مدیریت این رویداد تعریف میکنید. -
REMOVED_FROM_SPACE: این رویداد زمانی رخ میدهد که کاربر برنامه چت را از یک فضا یا دایرکت حذف کند. این رویداد پاسخی را به چت ارسال نمیکند. در Apps Script، شما یک تابعonRemoveFromSpace()برای مدیریت این رویداد تعریف میکنید. -
MESSAGE: این رویداد زمانی رخ میدهد که یک کاربر به برنامه چت، چه مستقیماً در یک پیام مستقیم (DM) و چه به صورت @mention در یک فاصله، پیام ارسال کند. در Apps Script، شما یک تابعonMessage()برای پاسخ به این رویداد تعریف میکنید. -
CARD_CLICKED: این رویداد زمانی رخ میدهد که کاربر روی دکمهای که یک عمل سفارشی به آن اختصاص داده شده است، کلیک کند. در Apps Script، شما یک تابعonCardClick()برای پاسخ به این رویداد تعریف میکنید.
محتویات فایل Code.gs را با کد زیر که هندلرهایی برای رویدادهای ADDED_TO_SPACE و REMOVE_FROM_SPACE تعریف میکند، جایگزین کنید. (در ادامهی این آزمایشگاه کد، هندلرهایی برای رویدادهای MESSAGE و CARD_CLICKED اضافه خواهید کرد.)
کد.gs
/**
* Responds to an ADDED_TO_SPACE event in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onAddToSpace(event) {
console.info(event);
var message = 'Thank you for adding me to ';
if (event.space.type === 'DM') {
message += 'a DM, ' + event.user.displayName + '!';
} else {
message += event.space.displayName;
}
return { text: message };
}
/**
* Responds to a REMOVED_FROM_SPACE event in Google Chat.
* @param {object} event the event object from Google Chat
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onRemoveFromSpace(event) {
console.info(event);
console.log('Chat app removed from ', event.space.name);
}
۴. انتشار و آزمایش برنامه چت
فایل مانیفست اسکریپت خود را بهروزرسانی کنید
قبل از اینکه بتوانید برنامه خود را در Chat منتشر کنید، باید مانیفست اسکریپت را بهروزرسانی کنید.
- روی تنظیمات پروژه کلیک کنید
. - کادر انتخاب نمایش فایل مانیفست "appsscript.json" در ویرایشگر را علامت بزنید .
- روی ویرایشگر کلیک کنید
. - روی فایل
appsscript.jsonکلیک کنید. - خط
"chat": {}را به فایل مانیفست خود اضافه کنید.
فایل مانیفست شما باید مشابه مثال زیر باشد.
appsscript.json
{
"timeZone": "America/Los_Angeles",
"dependencies": {
},
"chat": {}
}
ایجاد یک پروژه گوگل کلود
قبل از اینکه بتوانید برنامه چت را اجرا و آزمایش کنید، باید یک پروژه Google Cloud ایجاد کنید، API چت را فعال و پیکربندی کنید و برنامه چت خود را در سازمان Google Workspace خود منتشر کنید.
- در کنسول ابری گوگل به منو بروید
> مدیریت و ادمین > ایجاد یک پروژه .
- برای نام پروژه، یک نام توصیفی وارد کنید.
- در صورت درخواست، حساب سازمان و صورتحساب را انتخاب کنید.
- روی ایجاد کلیک کنید.
- وقتی ایجاد پروژه کامل شد، یک اعلان در بالا سمت راست صفحه ظاهر میشود. برای باز کردن پروژه، روی ورودی Create Project: <Project name> کلیک کنید.
- روی منو کلیک کنید > رابطهای برنامهنویسی کاربردی (API) و سرویسها > اعتبارنامهها .
- روی صفحه رضایت OAuth کلیک کنید.
- برای نام برنامه ، برنامه چت حضور و غیاب را وارد کنید.
- در صورت درخواست، ایمیل پشتیبانی کاربر و اطلاعات تماس توسعهدهنده را وارد کنید.
- روی ذخیره و ادامه کلیک کنید.
- روی تنظیمات و ابزارها کلیک کنید
> تنظیمات پروژه . - شماره پروژه را کپی کنید.
- به ویرایشگر اسکریپت برنامه برگردید، روی تنظیمات پروژه کلیک کنید .
- در زیر پروژه پلتفرم ابری گوگل (GCP) ، روی تغییر پروژه کلیک کنید.
- روی شماره پروژه GCP کلیک کنید و شماره پروژه را وارد کنید.
- روی تنظیم پروژه کلیک کنید.
انتشار برنامه در چت
برای انتشار برنامه چت خود در گوگل چت، موارد زیر را انجام دهید:
- در ویرایشگر اسکریپت برنامهها، روی Deploy > New deployment کلیک کنید.
- در کنار انتخاب نوع، روی فعال کردن انواع استقرار کلیک کنید. .
- افزونه را انتخاب کنید و روی «استقرار» کلیک کنید.
- شناسه استقرار را کپی کنید و روی «انجام شد» کلیک کنید.
- در کنسول گوگل کلود به منو بروید > رابطهای برنامهنویسی کاربردی (API) و سرویسها > کتابخانه .
- عبارت Google Chat API را جستجو کنید. API مورد نظر را از لیست نتایج انتخاب کنید.
- در صفحه Google Chat API، روی فعال کردن کلیک کنید.
- پس از فعال کردن API، روی پیکربندی کلیک کنید. هر پیامی که از شما میخواهد اعتبارنامه ایجاد کنید را نادیده بگیرید.
- در صفحه پیکربندی ، موارد زیر را انجام دهید:
- گزینه «ساخت این برنامه چت به عنوان یک افزونه فضای کاری» را پاک کنید و برای تأیید، روی غیرفعال کردن (DISABLE) کلیک کنید.
- برای نام برنامه ، برنامه چت حضور و غیاب را وارد کنید.
- برای آدرس اینترنتی آواتار ، https://goo.gl/kv2ENA را وارد کنید.
- برای توضیحات ، عبارت Apps Script codelab Chat app را وارد کنید.
- در بخش عملکرد ، گزینه دریافت پیامهای یک به یک را انتخاب کنید.
- در قسمت تنظیمات اتصال (Connection settings )، پروژه Apps Script را انتخاب کنید و شناسه استقرار (Deployment ID) اسکریپت خود را در کادر متن جایگذاری کنید.
- در قسمت مجوزها ، گزینه «افراد و گروههای خاص در دامنه شما» را انتخاب کنید. در کادر متنی زیر منوی کشویی، آدرس ایمیل مرتبط با سازمان Google Workspace خود را وارد کنید.
- روی ذخیره کلیک کنید.
پس از ذخیره تغییرات، تأیید کنید که وضعیت در صفحه Google Chat API، وضعیت برنامه را به صورت «فعال - در دسترس کاربران» نشان دهد.
برنامه چت را آزمایش کنید
برای آزمایش برنامه خود در گوگل چت، موارد زیر را انجام دهید:
- گوگل چت را باز کنید.
- با کلیک روی شروع چت، یک پیام مستقیم جدید به برنامه چت ارسال کنید
> برنامهها را پیدا کنید . - در صفحه یافتن برنامهها، برنامه Attendance Chat را جستجو کنید.
- در کنار برنامه چت حضور و غیاب ، روی افزودن > چت کلیک کنید.
وقتی بخش پیامهای مستقیم باز میشود، باید پیامی از برنامه چت ببینید که از شما برای اضافه کردن آن به دایرکت تشکر میکند، همانطور که در تصویر زیر نشان داده شده است.
۵. یک پاسخ با فرمت کارت تعریف کنید
در مرحله قبل، برنامه شما با یک پاسخ متنی ساده به رویدادهای Google Chat پاسخ داد. در این مرحله، برنامه خود را برای پاسخ دادن با کارتها بهروزرسانی میکنید.
پاسخهای کارت
گوگل چت از استفاده از کارتها برای پاسخها پشتیبانی میکند. کارتها محفظههای بصری هستند که به شما امکان میدهند مجموعهای از ویجتهای رابط کاربری را با هم گروهبندی کنید. کارتها میتوانند هدرها، پاراگرافهای متنی، مجموعهای از دکمهها، تصاویر و متن کلید/مقدار را نمایش دهند. برنامه شما میتواند یک یا چند کارت را در پاسخ JSON خود به گوگل چت تعریف کند، که سپس پاسخ شما را به عناصر رابط کاربری مربوطه ترجمه میکند.
تصویر زیر یک پاسخ کارتی با سه بخش را نشان میدهد که شامل یک هدر، یک ویجت کلید/مقدار، یک ویجت تصویر و یک دکمه متنی است.
برای پاسخ دادن به پیامهای کاربر با استفاده از پاسخ کارت، کد زیر را به فایل Code.gs برنامه چت خود اضافه کنید.
کد.gs
const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
header: {
title : 'Attendance Chat app',
subtitle : 'Log your vacation time',
imageUrl : DEFAULT_IMAGE_URL
}
};
/**
* Creates a card-formatted response.
* @param {object} widgets the UI components to send
* @return {object} JSON-formatted response
*/
function createCardResponse(widgets) {
return {
cards: [HEADER, {
sections: [{
widgets: widgets
}]
}]
};
}
/**
* Responds to a MESSAGE event triggered
* in Google Chat.
*
* @param event the event object from Google Chat
* @return JSON-formatted response
*/
function onMessage(event) {
const userMessage = event.message.text;
const widgets = [{
"textParagraph": {
"text": "You said: " + userMessage
}
}];
return createCardResponse(widgets);
}
تابع onMessage() که در این مرحله اضافه شده است، پیام اصلی کاربر را میخواند و پاسخی را به عنوان یک ویجت ساده TextParagragh میسازد. سپس تابع onMessage() تابع createCardResponse() را فراخوانی میکند که ویجت TextParagraph را در بخشی از یک کارت قرار میدهد. برنامه چت، شیء جاوا اسکریپت ساخته شده با پاسخ کارت را به Google Chat برمیگرداند.
برنامه چت را آزمایش کنید
برای آزمایش این برنامه، به پیام مستقیم خود با برنامه در Google Chat برگردید و یک پیام تایپ کنید (هر پیامی مناسب است).
توجه داشته باشید که کنترلکننده رویداد onMessage() شیء رویداد ارسالی توسط Google Chat را تجزیه میکند تا پیام اصلی کاربر را استخراج کند. همچنین میتوانید انواع دیگری از اطلاعات در مورد رویداد، از جمله نام کاربری که رویداد را آغاز کرده، آدرس ایمیل او، نام فضایی که رویداد در آن رخ داده است و موارد دیگر را دریافت کنید.
برای اطلاعات بیشتر در مورد ساختار اشیاء رویداد ارسال شده توسط Google Chat، به مرجع قالبهای رویداد مراجعه کنید.
۶. به کلیکهای دکمه در کارتها واکنش نشان دهید
در مرحله قبل، برنامه چت شما به پیامی از یک کاربر - یک رویداد MESSAGE - با یک کارت ساده که حاوی یک ویجت TextParagragh بود، پاسخ داد. در این مرحله، شما یک پاسخ ایجاد میکنید که شامل دکمههایی است که برای هر دکمه یک عمل سفارشی تعریف شده است.
کارتهای تعاملی
پاسخهای کارت میتوانند شامل یکی از دو نوع دکمه باشند: ویجتهای دکمه متنی، که دکمههای فقط متنی را نمایش میدهند؛ و ویجتهای دکمه تصویری، که دکمهای را با یک آیکون ساده یا تصویر بدون متن نمایش میدهند. هر دو ویجت TextButton و ImageButton از یکی از دو رفتار onClick (همانطور که در پاسخ JSON ارسال شده به Google Chat تعریف شده است) پشتیبانی میکنند: یا openLink یا action . همانطور که از نامش پیداست، openLink یک لینک مشخص را در یک تب جدید مرورگر باز میکند.
شیء action یک عمل سفارشی برای انجام دکمه مشخص میکند. میتوانید چندین مقدار دلخواه را در شیء action مشخص کنید، از جمله یک actionMethodName منحصر به فرد و مجموعهای از جفتهای پارامتر کلید/مقدار.
تعیین یک شیء action برای دکمه، یک کارت تعاملی ایجاد میکند. وقتی کاربر روی دکمه در پیام کلیک میکند، گوگل چت یک رویداد CARD_CLICKED را فعال میکند و درخواستی را به برنامهای که پیام اصلی را ارسال کرده است، ارسال میکند. سپس برنامه باید رویداد فعال شده از گوگل چت را مدیریت کند و پاسخی را به فضا برگرداند.
تابع onMessage() را در Code.gs با کد زیر جایگزین کنید. این کد دو دکمه ایجاد میکند، یکی تنظیم تعطیلات در Gmail و دیگری مسدود کردن روز در تقویم در کارت ارسالی به Google Chat.
کد.gs
const REASON = {
SICK: 'Out sick',
OTHER: 'Out of office'
};
/**
* Responds to a MESSAGE event triggered in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
*/
function onMessage(event) {
console.info(event);
const reason = REASON.OTHER;
const name = event.user.displayName;
const userMessage = event.message.text;
// If the user said that they were 'sick', adjust the image in the
// header sent in response.
if (userMessage.indexOf('sick') > -1) {
// Hospital material icon
HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
reason = REASON.SICK;
} else if (userMessage.indexOf('vacation') > -1) {
// Spa material icon
HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
}
const widgets = [{
textParagraph: {
text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
}
}, {
buttons: [{
textButton: {
text: 'Set vacation in Gmail',
onClick: {
action: {
actionMethodName: 'turnOnAutoResponder',
parameters: [{
key: 'reason',
value: reason
}]
}
}
}
}, {
textButton: {
text: 'Block out day in Calendar',
onClick: {
action: {
actionMethodName: 'blockOutCalendar',
parameters: [{
key: 'reason',
value: reason
}]
}
}
}
}]
}];
return createCardResponse(widgets);
}
برای مدیریت رویداد CARD_CLICKED ، باید تابع onCardClick() را به اسکریپت برنامه چت خود اضافه کنید. کد زیر را که تابع onCardClick() را تعریف میکند، Code.gs اضافه کنید.
کد.gs
/**
* Responds to a CARD_CLICKED event triggered in Google Chat.
* @param {object} event the event object from Google Chat
* @return {object} JSON-formatted response
* @see https://developers.google.com/workspace/chat/receive-respond-interactions
*/
function onCardClick(event) {
console.info(event);
let message = '';
const reason = event.action.parameters[0].value;
if (event.action.actionMethodName == 'turnOnAutoResponder') {
turnOnAutoResponder(reason);
message = 'Turned on vacation settings.';
} else if (event.action.actionMethodName == 'blockOutCalendar') {
blockOutCalendar(reason);
message = 'Blocked out your calendar for the day.';
} else {
message = "I'm sorry; I'm not sure which button you clicked.";
}
return { text: message };
}
در پاسخ به کلیکهای کاربر، اکنون برنامه چت یکی از این دو کار را انجام میدهد: پاسخگوی تعطیلات کاربر در Gmail را روی پیام "خارج از دفتر" تنظیم میکند؛ یا یک جلسه تمام روز را در تقویم کاربر برنامهریزی میکند. برای انجام این وظایف، برنامه سرویس پیشرفته Gmail و سرویس تقویم را فراخوانی میکند.
کد زیر را به اسکریپت خود اضافه کنید تا برنامه چت را با Gmail و Calendar ادغام کنید.
کد.gs
const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
* Turns on the user's vacation response for today in Gmail.
* @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
*/
function turnOnAutoResponder(reason) {
let currentTime = (new Date()).getTime();
Gmail.Users.Settings.updateVacation({
enableAutoReply: true,
responseSubject: reason,
responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
restrictToContacts: true,
restrictToDomain: true,
startTime: currentTime,
endTime: currentTime + ONE_DAY_MILLIS
}, 'me');
}
/**
* Places an all-day meeting on the user's Calendar.
* @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
*/
function blockOutCalendar(reason) {
CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}
در نهایت، باید سرویس پیشرفته Gmail را در پروژه فعال کنید. برای فعال کردن Gmail API، موارد زیر را انجام دهید:
- در ویرایشگر اسکریپت برنامهها، در کنار سرویسها ، روی افزودن سرویس کلیک کنید. .
- API جیمیل را انتخاب کنید.
- روی داشبورد API پلتفرم ابری گوگل در زیر کلیک کنید تا کنسول ابری گوگل باز شود.
- روی فعال کردن APIها و سرویسها کلیک کنید.
- عبارت Gmail API را جستجو کنید و روی Gmail API کلیک کنید.
- در صفحه Gmail API، روی فعال کردن کلیک کنید.
برنامه چت را آزمایش کنید
برای آزمایش این نسخه از برنامه چت خود، دایرکتی را که در مراحل قبلی در گوگل چت شروع کردید باز کنید و عبارت «من به تعطیلات میروم» را تایپ کنید. برنامه باید با کارتی مشابه تصویر زیر پاسخ دهد.
توجه: اگر از شما خواسته شود به برنامه دسترسی بدهید، ممکن است مجبور شوید پیام خود را برای بار دوم تایپ کنید.
۷. تبریک میگویم!
برنامه چت شما اکنون میتواند به پیامهای کاربران پاسخ دهد، پاسخگوی تعطیلات آنها را در Gmail تنظیم کند و یک رویداد تمام روز را در تقویم آنها قرار دهد.
آنچه ما پوشش دادهایم
- یک برنامه Google Chat با Apps Script ایجاد و منتشر کردم
- با یک پاسخ ساده به پیامهای کاربران پاسخ داده شد
- از طرف کاربر و از طریق برنامه چت، با سایر سرویسهای Google Workspace تعامل داشت