1. مقدمه
برنامه‌های گپ Google سرویس‌ها و منابع را مستقیماً به چت می‌آورند، جایی که کاربران اطلاعات دریافت می‌کنند و می‌توانند بدون ترک مکالمه اقدام کنند.
در این لبه کد، می‌آموزید که چگونه یک برنامه چت ایجاد کنید - «برنامه گفتگوی حضور و غیاب» - که پاسخگویان تعطیلات را در Gmail تنظیم می‌کند و جلسات را در تقویم Google زمان‌بندی می‌کند. با ساختن برنامه Attendance Chat در Google Apps Script ، می‌توانید به راحتی به سایر سرویس‌های Google مانند Drive، Gmail، Calendar، Docs، Sheets و موارد دیگر دسترسی داشته باشید.
چیزی که یاد خواهید گرفت
- نحوه اضافه کردن کنترل کننده در رویدادهایی که در Chat مطرح می شوند
- نحوه تجزیه اشیاء رویداد ارسال شده از چت
- نحوه پاسخ دادن به چت با پاسخ‌های قالب‌بندی شده با کارت
- نحوه تعریف و واکنش به اقدامات سفارشی برای کلیک دکمه در کارت ها
آنچه شما نیاز دارید
- دسترسی به اینترنت و مرورگر وب.
- یک حساب Google Workspace با دسترسی به Google Chat .
- مهارت‌های پایه جاوا اسکریپت - Google Apps Script فقط از جاوا اسکریپت پشتیبانی می‌کند.
2. کد نمونه را دریافت کنید
می‌توانید یک فایل ZIP دانلود کنید یا مخزن GitHub را کلون کنید تا کد هر مرحله را در این نمونه ببینید.
پوشه‌های step-NN در solutions/attendance-chat-app حاوی وضعیت پایان مطلوب هر مرحله از این کد لبه هستند. آنها برای مرجع وجود دارد.
کد را دانلود کنید
برای دانلود کد این کد لبه روی دکمه زیر کلیک کنید:
فایل ZIP دانلود شده را باز کنید. این یک پوشه ریشه ( apps-script-samples ) را باز می‌کند، که حاوی یک پوشه برای هر مرحله از این کد لبه تحت solutions/attendance-chat-app است.
مخزن GitHub را کلون کنید
برای کلون کردن مخزن GitHub برای این کد لبه، دستور زیر را اجرا کنید:
git clone https://github.com/googleworkspace/apps-script-samples
3. کنترل‌کننده‌های رویدادهای چت Google را ایجاد کنید
یک پروژه Apps Script ایجاد کنید
برای ایجاد یک پروژه Apps Script، مراحل زیر را انجام دهید:
- به script.new بروید.
- پروژه Untitled را کلیک کنید.
- نام اسکریپت برنامه Attendance Chat را تغییر دهید و روی تغییر نام کلیک کنید.
رویدادها در Google Chat
بیشتر تعاملات Apps Script با Chat مبتنی بر رویداد است. تعامل بین کاربر، برنامه چت و چت معمولاً از این ترتیب است:
- کاربر اقدامی را آغاز می‌کند، مانند افزودن یک برنامه چت به یک فضا، شروع یک پیام مستقیم (DM) با یک برنامه چت، یا حذف یک برنامه چت از یک فضا.
- این اقدام یک رویداد را با هدف برنامه Chat در Chat ایجاد می کند.
- Chat کنترل کننده رویداد مربوطه را که در اسکریپت برنامه Chat تعریف شده است فراخوانی می کند.
Chat 4 رویدادی را ایجاد می کند که برنامه شما می تواند به آنها گوش دهد:
-
ADDED_TO_SPACE: این رویداد زمانی رخ می‌دهد که کاربر انسانی یک برنامه چت را به یک فضا یا یک پیام مستقیم (DM) اضافه می‌کند. در Apps Script، یک تابعonAddToSpace()برای مدیریت این رویداد تعریف می کنید. -
REMOVED_FROM_SPACE: این رویداد زمانی رخ می‌دهد که کاربر برنامه چت را از یک فضا یا DM حذف کند. این رویداد پاسخی به گپ ارسال نمی کند. در Apps Script، یک تابعonRemoveFromSpace()برای مدیریت این رویداد تعریف می کنید. -
MESSAGE: این رویداد زمانی رخ می‌دهد که کاربر مستقیماً از طریق DM یا به‌عنوان نام @ در یک فاصله، به برنامه Chat پیام می‌دهد. در Apps Script، یک تابعonMessage()برای پاسخ به این رویداد تعریف می‌کنید. -
CARD_CLICKED: این رویداد زمانی رخ می‌دهد که کاربر روی دکمه‌ای کلیک می‌کند که یک اقدام سفارشی به آن اختصاص داده شده است. در Apps Script، یک تابعonCardClick()برای پاسخ به این رویداد تعریف می‌کنید.
محتوای فایل Code.gs را با کد زیر جایگزین کنید که کنترل‌کننده‌هایی را برای رویدادهای ADDED_TO_SPACE و REMOVE_FROM_SPACE تعریف می‌کند. (شما کنترل کننده هایی را برای رویدادهای MESSAGE و CARD_CLICKED بعداً در این آزمایشگاه کد اضافه خواهید کرد.)
Code.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);
}
4. برنامه چت را منتشر و آزمایش کنید
فایل مانیفست اسکریپت خود را به روز کنید
قبل از اینکه بتوانید برنامه خود را در چت منتشر کنید، باید مانیفست اسکریپت را به روز کنید.
- روی تنظیمات پروژه کلیک کنید
. - کادر بررسی نمایش فایل مانیفست "appsscript.json" در ویرایشگر را انتخاب کنید.
- روی ویرایشگر کلیک کنید
. - روی فایل
appsscript.jsonکلیک کنید. - خط
"chat": {}را به فایل مانیفست خود اضافه کنید.
فایل مانیفست شما باید شبیه به مثال زیر باشد.
appsscript.json
{
"timeZone": "America/Los_Angeles",
"dependencies": {
},
"chat": {}
}
یک پروژه Google Cloud ایجاد کنید
قبل از اینکه بتوانید برنامه Chat را اجرا و آزمایش کنید، باید یک پروژه Google Cloud ایجاد کنید، Chat API را فعال و پیکربندی کنید، و برنامه Chat خود را در سازمان Google Workspace خود منتشر کنید.
- در Google Cloud Console به منو بروید
> IAM & Admin > ایجاد یک پروژه .
- برای نام پروژه یک نام توصیفی وارد کنید.
- در صورت درخواست، سازمان و حساب صورت‌حساب را انتخاب کنید.
- روی ایجاد کلیک کنید.
- هنگامی که ساخت پروژه کامل شد، یک اعلان در سمت راست بالای صفحه ظاهر می شود. روی ورودی Create Project: <Project name> کلیک کنید تا پروژه باز شود.
- روی منو کلیک کنید > API ها و خدمات > اعتبارنامه ها .
- روی صفحه رضایت OAuth کلیک کنید.
- برای نام برنامه ، برنامه Attendance Chat را وارد کنید.
- در صورت درخواست، ایمیل پشتیبانی کاربر و اطلاعات تماس برنامه‌نویس را وارد کنید.
- روی ذخیره و ادامه کلیک کنید.
- روی Settings and Utilities کلیک کنید
> تنظیمات پروژه - شماره پروژه را کپی کنید.
- در ویرایشگر برنامه اسکریپت، روی تنظیمات پروژه کلیک کنید .
- در پروژه Google Cloud Platform (GCP) ، روی تغییر پروژه کلیک کنید.
- روی شماره پروژه GCP کلیک کنید و شماره پروژه را وارد کنید.
- روی تنظیم پروژه کلیک کنید.
برنامه را در چت منتشر کنید
برای انتشار برنامه چت در Google Chat، موارد زیر را انجام دهید:
- در ویرایشگر Apps Script، روی Deploy > New Deployment کلیک کنید.
- در کنار Select type روی Enable Deployment Types کلیک کنید .
- Add-on را انتخاب کنید و روی Deploy کلیک کنید.
- Deployment ID را کپی کنید و روی Done کلیک کنید.
- در کنسول Google Cloud به منو بروید > APIها و خدمات > کتابخانه .
- Google Chat API را جستجو کنید. API را از لیست نتایج انتخاب کنید.
- در صفحه Google Chat API، روی فعال کردن کلیک کنید.
- پس از فعال کردن API، روی Configuration کلیک کنید. هر پیامی که از شما می خواهد اعتبارنامه ایجاد کنید نادیده بگیرید.
- در صفحه تنظیمات ، موارد زیر را انجام دهید:
- برای نام برنامه ، برنامه Attendance Chat را وارد کنید.
- برای آدرس آواتار ، https://goo.gl/kv2ENA را وارد کنید.
- برای توضیحات ، Apps Script codelab Chat app را وارد کنید.
- در بخش عملکرد ، دریافت پیام های یک به یک را انتخاب کنید.
- در قسمت تنظیمات اتصال ، پروژه Apps Script را انتخاب کنید و شناسه استقرار اسکریپت خود را در کادر متنی قرار دهید.
- در قسمت مجوزها ، افراد و گروه‌های خاص را در دامنه خود انتخاب کنید. در کادر نوشتاری زیر منوی کشویی، آدرس ایمیل مرتبط با سازمان Google Workspace خود را وارد کنید.
- روی ذخیره کلیک کنید.
پس از اینکه تغییرات خود را ذخیره کردید، بررسی کنید که وضعیت در صفحه Google Chat API وضعیت برنامه را به صورت زنده نشان دهد - در دسترس کاربران است .
برنامه چت را تست کنید
برای آزمایش برنامه خود در Google Chat، موارد زیر را انجام دهید:
- Google Chat را باز کنید.
- با کلیک روی Start a chat یک پیام مستقیم جدید به برنامه Chat ارسال کنید
> برنامه ها را پیدا کنید . - در صفحه یافتن برنامه‌ها، برنامه Attendance Chat را جستجو کنید.
- در کنار برنامه Attendance Chat ، روی Add > Chat کلیک کنید.
همانطور که در تصویر زیر نشان داده شده است، وقتی رشته پیام مستقیم باز می شود، باید پیامی را از برنامه چت ببینید که از شما برای افزودن آن به DM تشکر می کند.
5. پاسخی با فرمت کارت تعریف کنید
در مرحله قبل، برنامه شما با یک پاسخ متنی ساده به رویدادهای Google Chat پاسخ داد. در این مرحله، برنامه خود را به‌روزرسانی می‌کنید تا با کارت پاسخ دهد.
پاسخ های کارت
Google Chat از استفاده از کارت برای پاسخ‌ها پشتیبانی می‌کند. کارت ها محفظه های بصری هستند که به شما امکان می دهند مجموعه ای از ویجت های رابط کاربری را با هم گروه بندی کنید. کارت ها می توانند سرصفحه ها، پاراگراف های متنی، مجموعه ای از دکمه ها، تصاویر و متن کلید/مقدار را نمایش دهند. برنامه شما می‌تواند یک یا چند کارت را در پاسخ JSON به Google Chat تعریف کند، که سپس پاسخ شما را به عناصر رابط کاربری مربوطه ترجمه می‌کند.
تصویر زیر پاسخ کارت را با سه بخش نشان می‌دهد که شامل سرصفحه، ویجت کلید/مقدار، ویجت تصویر و دکمه متن است.
برای پاسخ دادن به پیام‌های کاربر با پاسخ کارت، کد زیر را به فایل Code.gs برنامه چت خود اضافه کنید.
Code.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 را در بخشی از یک کارت قرار می دهد. برنامه Chat شی جاوا اسکریپت ساخته شده با پاسخ کارت را به چت Google برمی گرداند.
برنامه چت را تست کنید
برای آزمایش این برنامه، به پیام مستقیم خود با برنامه در Google Chat برگردید و پیامی را تایپ کنید (هر پیامی انجام خواهد شد).
توجه داشته باشید که کنترل کننده رویداد onMessage() شی رویداد ارسال شده توسط Google Chat را برای استخراج پیام اصلی کاربر تجزیه می کند. همچنین می توانید انواع دیگری از اطلاعات مربوط به رویداد را دریافت کنید، از جمله نام کاربری که رویداد را آغاز کرده است، آدرس ایمیل او، نام فضایی که رویداد در آن رخ داده است، و بسیاری موارد دیگر.
برای اطلاعات بیشتر درباره ساختار اشیاء رویداد ارسال شده توسط Google Chat، به مرجع قالب‌های رویداد مراجعه کنید.
6. به کلیک دکمه ها در کارت ها واکنش نشان دهید
در مرحله قبل، برنامه چت شما با یک کارت ساده که حاوی یک ویجت TextParagragh بود، به پیام یک کاربر - یک رویداد MESSAGE - پاسخ داد. در این مرحله شما پاسخی ایجاد می کنید که شامل دکمه هایی می شود که هر دکمه یک عمل سفارشی برای آن تعریف شده است.
کارت های تعاملی
پاسخ‌های کارت می‌توانند شامل یکی از دو نوع دکمه باشند: ویجت‌های دکمه متن، که دکمه‌های فقط متنی را نمایش می‌دهند. و ابزارک ImageButton که دکمه ای را با یک نماد ساده یا تصویر بدون متن نمایش می دهند. هر دو ویجت TextButton و ImageButton یکی از دو رفتار onClick را پشتیبانی می‌کنند (همانطور که در پاسخ JSON ارسال شده به Google Chat تعریف شده است): یا openLink یا action . همانطور که از نام آن پیداست، openLink یک پیوند مشخص شده را در یک برگه مرورگر جدید باز می کند.
شیء action یک عمل سفارشی را برای انجام دکمه مشخص می کند. شما می توانید چندین مقدار دلخواه را در شی اکشن مشخص کنید، از جمله یک actionMethodName منحصر به فرد و مجموعه ای از جفت پارامتر کلید/مقدار.
تعیین یک شیء action برای دکمه، یک کارت تعاملی ایجاد می کند. وقتی کاربر روی دکمه موجود در پیام کلیک می‌کند، Google Chat یک رویداد CARD_CLICKED را مطرح می‌کند و درخواستی را به برنامه‌ای که پیام اصلی را ارسال کرده است، ارسال می‌کند. سپس برنامه باید رویداد مطرح شده از Google Chat را مدیریت کند و پاسخی را به فضا بازگرداند.
تابع onMessage() را در Code.gs با کد زیر جایگزین کنید. این کد 2 دکمه ایجاد می‌کند، یک تعطیلات را در Gmail تنظیم کنید و یک دکمه Block out را در تقویم در کارت ارسال شده به Google Chat.
Code.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 تعریف می کند.
Code.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 و سرویس Calendar را فراخوانی می کند.
کد زیر را به اسکریپت خود اضافه کنید تا برنامه چت با جیمیل و تقویم یکپارچه شود.
Code.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 API، موارد زیر را انجام دهید:
- در ویرایشگر Apps Script، در کنار Services ، روی Add a service کلیک کنید .
- Gmail API را انتخاب کنید.
- روی داشبورد Google Cloud Platform API در زیر کلیک کنید تا کنسول Google Cloud باز شود.
- روی Enable APIs and Services کلیک کنید.
- Gmail API را جستجو کنید و روی Gmail API کلیک کنید.
- در صفحه Gmail API، روی Enable کلیک کنید.
برنامه چت را تست کنید
برای آزمایش این نسخه از برنامه Chat خود، DM را که در مراحل قبلی در Google Chat شروع کرده‌اید باز کنید و I'm going to vacation را تایپ کنید. برنامه باید با کارتی مشابه تصویر زیر پاسخ دهد.
توجه: اگر از شما خواسته شد دسترسی به برنامه را فراهم کنید، ممکن است مجبور شوید پیام خود را برای بار دوم تایپ کنید.
7. تبریک می گویم!
برنامه چت شما اکنون می‌تواند به پیام‌های کاربر پاسخ دهد، پاسخگوی تعطیلات آنها را در Gmail تنظیم کند، و یک رویداد تمام روز را در تقویم آنها قرار دهد.
آنچه را پوشش داده ایم
- یک برنامه Google Chat با Apps Script ایجاد و منتشر کرد
- با یک پاسخ ساده به پیام های کاربر پاسخ داد
- از طرف کاربر از طریق برنامه چت با سایر خدمات Google Workspace تعامل داشت