اگر برنامه Chat ساخته و منتشر کردهاید که برافزای Google Workspace نیست، این صفحه نشان میدهد چگونه آن را به برافزای Google Workspace تبدیل کنید که Google Chat را گسترش میدهد.
با تبدیل کردن، برنامه Google Chat شما میتواند از چارچوب برافزاهای Google Workspace استفاده کند و امکانات جدیدی برای یکپارچهسازی و ویژگیها در Google Chat و سراسر Google Workspace فراهم کند. برای مثال، میتوانید یک برافزای Google Workspace را ازطریق Google Workspace Marketplace توزیع کنید که برنامههای Chat را همراه با دیگر برنامههای میزبان Google Workspace، مثل Gmail، «تقویم»، و «سندنگار» گسترش میدهد.
محدودیتها
پیشاز شروع تبدیل، محدودیتها و ملاحظات مربوط به برافزاهای Google Workspace را بررسی کنید تا مطمئن شوید برنامه Chat شما که برافزا نیست میتواند بدون ازدست دادن عملکرد ضروری تبدیل شود.
مرحله ۱: کپی کردن کد برنامه Google Chat موجود
فرایند تبدیل نیاز به تغییرات کد دارد. برای اینکه برنامه Google Chat زنده شما تحت تأثیر قرار نگیرد، کپیای از کدتان ایجاد کنید و روی آن کار کنید.
Apps Script
- پروژه Google Apps Script برنامه Google Chat موجودتان را باز کنید.
- در سمت راست، روی نمای کلی کلیک کنید.
- در سمت چپ، روی تهیه رونوشت کلیک کنید.
- در سمت راست، روی تنظیمات پروژه کلیک کنید.
- در بخش پروژه Google Cloud، روی تغییر پروژه کلیک کنید.
- شماره پروژه مرتبط با برنامه Google Chat موجودتان را وارد کنید.
- روی تنظیم پروژه کلیک کنید.
HTTP
انشعاب یا کپی از پایگاه کد موجودتان ایجاد کنید و آن را بهعنوان سرویس جدیدی جدا از برنامه Google Chat فعال خودتان مستقر کنید.
اگر برنامه شما در Google Cloud مستقر شده است و به ویژگیهای مرتبط با پروژه Google Cloud (برای مثال، هویت پیشفرض App Engine) متکی است، کد جدید باید در سرویس مرتبط با پروژه برنامه Google Chat موجود مستقر شود.
مرحله ۲: اصلاح کد کپیشده
برافزاهای Google Workspace که Google Chat را گسترش میدهند در مقایسه با برنامههای Chat که برافزا نیستند از ساختارهای درخواست و پاسخ متفاوتی استفاده میکنند. باید کدتان را بهروز کنید تا بهجای
رویدادهای تعامل «میانای برنامهسازی کاربردی Google Chat» (Event)
از
اشیا رویداد برافزای Google Workspace (EventObject)
برای درخواستها و پاسخها استفاده کنید.
برای اصلاح کد خود، از راهنمای تبدیل کد استفاده کنید.
مرحله ۳: پیکربندی برافزای Google Workspace را برای کاربران آزمایشی فعال کنید
از کنسول Google Cloud برای پیکربندی تنظیمات برافزای Google Workspace برای برنامه Google Chat خود استفاده کنید:
به صفحه پیکربندی Google Chat API در کنسول Google Cloud بروید.
در بخش ویژگیهای تعاملی، فعال کردن ویژگیهای تعاملی را روشن کنید.
در بخش تبدیل به برافزای Google Workspace، روی تبدیل به برافزا کلیک کنید.
روشن کردن تنظیمات پیکربندی برافزا را فعال کنید.
در بخش رؤیتپذیری، نشانیهای ایمیل کاربران آزمایشیتان را اضافه کنید.
درصورت لزوم، تنظیمات اتصال را با نشانی اینترنتی نقطه پایانی پیادهسازی یا شناسه پیادهسازی Apps Script کد برنامه Google Chat که در «مرحله ۲» کپی و اصلاح کردهاید بهروزرسانی کنید.
روی ذخیره و آزمایش کلیک کنید.
مرحله ۴: آزمایش برنامه تبدیلشده
عملکرد برافزای Google Workspace را بااستفاده از حسابهای کاربر آزمایشی که در «مرحله ۳» پیکربندی شده است بهطور کامل آزمایش کنید. همه ویژگیها و تعاملها را درستیسنجی کنید.
مرحله ۵: تبدیل را برای همه کاربران تکمیل کنید
پساز اینکه مطمئن شدید برافزای تبدیلشده Google Workspace بهدرستی کار میکند، میتوانید آن را برای همه کاربران دردسترس قرار دهید.
به صفحه پیکربندی Google Chat API در کنسول Google Cloud بروید.
در بخش ویژگیهای تعاملی، روی تبدیل به برافزا کلیک کنید. پانل کناری باز میشود.
در پانل کناری، روی تبدیل به برافزا کلیک کنید.
«شناسه پروژه» خود را تایپ کنید و روی تبدیل کلیک کنید.
برنامه Google Chat شما اکنون برافزای Google Workspace است که Google Chat را گسترش میدهد.
اختیاری: پاکسازی یا آزاد کردن منابع Google Cloud استفادهنشده
درصورت تمایل، پساز تبدیل برنامه Google Chat به برافزای Google Workspace، برای جلوگیری از کسر هزینه از حساب Google Cloud برای منابعی که برنامه Google Chat استفاده میکند و دیگر استفاده نمیشود، آنها را خاموش کنید.
راهنمای تبدیل کد
این بخش جزئیات نگاشت بین تعامل «میانای برنامهسازی کاربردی Google Chat»
Event
قالب و برافزای Google Workspace
EventObject
قالب را شرح میدهد.
درخواست نگاشت
جدول زیر نشان میدهد که چگونه فیلدهای Google Chat API
Event برای
برنامه Chat که برافزا نیست
به فیلدهای مربوطه در برافزای Google Workspace
EventObject نگاشت میشوند.
برنامه گپی که برافزا نیست (فیلد Event) |
فیلد EventObject برافزای Google Workspace |
یادداشتها |
|---|---|---|
action.actionMethodName |
موجود نیست | برای تعاملات کارت، نام روش میتواند بهعنوان پارامتر در commonEventObject.parameters ارسال شود. باز کردن کادر گفتگوی اولیه را ببینید. |
action.parameters |
commonEventObject.parameters |
|
appCommandMetadata |
chat.appCommandPayload.appCommandMetadata |
|
common |
commonEventObject |
|
configCompleteRedirectUrl |
|
بسته به نوع رویداد، در بار دادههای مختلف دردسترس است. |
dialogEventType |
|
بسته به نوع رویداد، در بار دادههای مختلف دردسترس است. |
eventTime |
chat.eventTime |
|
isDialogEvent |
|
بسته به نوع رویداد، در بار دادههای مختلف دردسترس است. |
message |
|
بسته به نوع رویداد، در بار دادههای مختلف دردسترس است. |
space |
|
|
thread |
|
بسته به نوع رویداد، در بار دادههای مختلف دردسترس است. |
threadKey |
|
بسته به نوع رویداد، در بار دادههای مختلف دردسترس است. |
token |
موجود نیست | درستیسنجی بهصورت متفاوتی انجام میشود، به درخواست درستیسنجی برای برنامههای HTTP مراجعه کنید. |
type |
موجود نیست | نوع رویداد را میتوان از راهانداز استنباط کرد. |
user |
chat.user |
درخواست نگاشت براساس مورد استفاده
جدول زیر تفاوتهای پایهبارهای درخواست را برای موارد استفاده رایج بین برنامههای Chat که برافزا نیستند و برافزاهای Google Workspace که Google Chat را گسترش میدهند نشان میدهد.
| کاربرد | برنامه گپی که برافزا نیست (Event بار) |
برافزای Google Workspace EventObject پایهبار |
|---|---|---|
| برنامه به فضا اضافه شد | { "type": "ADDED_TO_SPACE", "space": { ... } } |
{ "chat": { "addedToSpacePayload": { "space": { ... } } } } |
| برداشتن برنامه از فضا | { "type": "REMOVED_FROM_SPACE", "space": { ... } } |
{ "chat": { "removedFromSpacePayload": { "space": { ... } } } } |
| کاربر از برنامهای @نام میبرد | { "type": "MESSAGE", "message": { ... }, "space": { ... }, "configCompleteRedirectUrl": "..." } |
{ "chat": { "messagePayload": { "message": { ... }, "space": { ... }, "configCompleteRedirectUri": "..." } } } |
| کاربر از برنامه @نامبری میکند تا آن را به فضا اضافه کند | باید به یک درخواست از Google Chat رسیدگی کنید:{ "type": "ADDED_TO_SPACE", "space": { ... }, "message": { ... } } |
باید دو درخواست از Google Chat را مدیریت کنید. درخواست اول: { "chat": { "addedToSpacePayload": { "space": { ... }, "interactionAdd": true } } } درخواست دوم: { "chat": { "messagePayload": { "message": { ... }, "space": { ... } } } } |
| فرمان خط مورب | { "type": "MESSAGE", "message": { "slashCommand": { ... } }, "space": { ... } } |
{ "chat": { "appCommandPayload": { "message": { ... }, "space": { ... }, "appCommandMetadata": { ... } } } } |
| فرمان خط مورب برای افزودن برنامه به فضا | باید به یک درخواست از Google Chat رسیدگی کنید:{ "type": "ADDED_TO_SPACE", "space": { ... }, "message": { "slashCommand": { ... } } } |
باید دو درخواست از Google Chat را مدیریت کنید. درخواست اول: { "chat": { "addedToSpacePayload": { "space": { ... }, "interactionAdd": true } } } درخواست دوم: { "chat": { "appCommandPayload": { "message": { ... }, "space": { ... }, "appCommandMetadata": { ... } } } } |
| کاربر روی دکمهای در کارت یا کادر گفتگو کلیک میکند | { "type": "CARD_CLICKED", "common": { ... }, "space": { ... }, "message": { ... }, "isDialogEvent": "...", "dialogEventType": "..." } برای رویدادهای کادر گفتگو، { "type": "CARD_CLICKED", "common": { "formInputs": { "contactName": { "": { "stringInputs": { "value": ["Kai 0"] }} } } }, "space": { ... }, "message": { ... }, "isDialogEvent": true, "dialogEventType": "..." } |
{ "commonEventObject": { ... }, "chat": { "buttonClickedPayload": { "message": { ... }, "space": { ... }, "isDialogEvent": "...", "dialogEventType": "..." } } } برای رویدادهای کادر گفتگو، { "commonEventObject": { "formInputs": { "contactName": { "stringInputs": { "value": ["Kai 0"] } } } }, "chat": { "buttonClickedPayload": { "message": { ... }, "space": { ... }, "isDialogEvent": "true", "dialogEventType": "..." } } } |
| کاربر اطلاعات را در کارت صفحه اصلی برنامه ارسال میکند | { "type": "SUBMIT_FORM", "common": { ... }, "space": { ... }, "message": { ... }, "isDialogEvent": "...", "dialogEventType": "..." } |
{ "commonEventObject": { ... }, "chat": { "buttonClickedPayload": { "message": { ... }, "space": { ... }, "isDialogEvent": "...", "dialogEventType": "SUBMIT_DIALOG" } } } |
| کاربر بااستفاده از فرمان سریع، فرمان برنامهای را فرا میخواند | { "type": "APP_COMMAND", "space": { ... }, "isDialogEvent": "...", "dialogEventType": "..." } |
{ "chat": { "appCommandPayload": { "message": { ... }, "space": { ... }, "appCommandMetadata": { ... } } } } |
| پیشنمایش پیوند | { "type": "MESSAGE", "message": { "matchedUrl": "..." }, "space": { ... } } |
{ "chat": { "messagePayload": { "message": { "matchedUrl": "..." }, "space": { ... } } } } |
| کاربر ابزارهای را در پیام کارت یا کادر گفتگو بهروز میکند | { "type": "WIDGET_UPDATED", "space": { ... }, "common": { ... } } |
{ "commonEventObject": { ... }, "chat": { "widgetUpdatedPayload": { "space": { ... } } } } |
تخصیص پاسخ براساس مورد استفاده
برافزاهای Google Workspace که Google Chat را گسترش میدهند، بهجای
Message شیء، کنش برمیگردانند. جدول زیر انواع پاسخهای Message Google Chat API را برای برنامه Chat که برافزا نیست به معادلهای کنش برافزای Google Workspace آنها نگاشت میکند.
| کاربرد | برنامه گپی که برافزا نیست (Message پاسخ) |
پاسخ برافزای Google Workspace به کنش Chat |
|---|---|---|
| ایجاد پیام در فضای فراخواندهشده | { "actionResponse": { "type": "NEW_MESSAGE" }, "text": "..." } |
{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": { "text": "..." } } } } } برای کسب اطلاعات بیشتر، پاسخ با پیام را ببینید. |
| بهروز کردن پیام | { "actionResponse": { "type": "UPDATE_MESSAGE" }, "text": "..." } برای کسب اطلاعات بیشتر، به بهروزرسانی پیام مراجعه کنید. |
{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": { "message": { "text": "..." } } } } } برای کسب اطلاعات بیشتر، به بهروزرسانی پیام مراجعه کنید. |
| پیشنمایش پیوند | { "actionResponse": { "type": "UPDATE_USER_MESSAGE_CARDS" }, "cardsV2": [{ ... }] } برای اطلاعات بیشتر، پیشنمایش پیوندها را ببینید. |
{ "hostAppDataAction": { "chatDataAction": { "updateInlinePreviewAction": { "cardsV2": [{ ... }] } } } } برای اطلاعات بیشتر، پیشنمایش پیوندها را ببینید. |
| باز کردن کادر گفتگوی اولیه | { "actionResponse": { "type": "DIALOG", "dialogAction": { "dialog": { "body": { /* Card object */ } } } } } برای کسب اطلاعات بیشتر، باز کردن کادرهای گفتگوی تعاملی را ببینید. |
{ "action": { "navigations": [{ "pushCard": { /* Card object */ } }] } } کارتی که ارسال میکنید میتواند حاوی ابزارکهایی با onClick کنش باشد. برای برافزاهای Google Workspace اچتیتیپی، این کنشها را برای فراخوانی نقطه پایانی تابع پیکربندی کنید: { "onClick": { "action": { "function": "https://...", "parameters": [{ "key": "clickedButton", "value": "submit" }] } } } برای کسب اطلاعات بیشتر، باز کردن کادرهای گفتگوی تعاملی را ببینید. |
| بستن کادر گفتگو | { "actionResponse": { "type": "DIALOG", "dialogAction": { "actionStatus": { "userFacingMessage": "..." } } } } برای کسب اطلاعات بیشتر، بستن کادر گفتگو را ببینید. |
{ "action": { "navigations": [{ "endNavigation": "CLOSE_DIALOG" }], "notification": { "text": "..."} } } برای کسب اطلاعات بیشتر، بستن کادر گفتگو را ببینید. |
| اتصال به سیستم خارجی (درخواست پیکربندی) | { "actionResponse": { "type": "REQUEST_CONFIG", "url": "..." } } برای کسب اطلاعات بیشتر، اتصال به سیستم خارجی (برنامههای Chat که برافزا نیستند) را ببینید. |
{ "basic_authorization_prompt": { "authorization_url": "...", "resource": "..." } } برای کسب اطلاعات بیشتر، اتصال برنامه Chat به سرویسها و ابزارهای دیگر را ببینید. |
| تکمیل خودکار موارد در ابزارههای تعاملی | { "actionResponse": { "type": "UPDATE_WIDGET", "updatedWidget": { "suggestions": { "items": ["..."] }, "widget": "widget_id" } } } برای اطلاعات بیشتر، افزودن منو چندانتخابی را ببینید. |
{ "action": { "modifyOperations": [{ "updateWidget": { "widgetId": "widget_id", "selectionInputWidgetSuggestions": { "suggestions": ["..."] } } }] } } برای کسب اطلاعات بیشتر، خواندن ورودی دادههای فرم توسط کاربران در کارتها را ببینید. |
مدیریت تعاملات کارت در پیامهای ایجادشده قبلاز تبدیل
وقتی برنامه «گپ HTTP» را که برافزا نیست به برافزای Google Workspace تبدیل میکنید، تعاملهای کارت در پیامهایی که قبلاز تبدیل ایجاد شدهاند نیاز به مدیریت ویژه دارند. برافزاها از نشانی وب HTTP کامل برای action.function کارت استفاده میکنند، درحالیکه برنامههای «گپ» که برافزا نیستند از نام تابع استفاده میکنند.
جدول زیر این تفاوتها را خلاصه میکند.
| برنامه گپی که برافزا نیست | برافزای Google Workspace که Google Chat را گسترش میدهد | |
|---|---|---|
| پیکربندی | یک نقطه پایانی واحد برای همه رویدادها در کنسول Google Cloud پیکربندی میکنید. هنگام پیادهسازی تعاملات کارت، action کارت فقط حاوی نام تابعی است که باید اجرا شود. نقطه پایانی HTTP مشترک برای رویدادهای کلیک کارت فراخوانی میشود.
برای کسب اطلاعات بیشتر، باز کردن کادرهای گفتگوی تعاملی را ببینید. { "onClick": { "action": { "function": "submit" } } } |
میتوانید بهصورت اختیاری نقطههای پایانی هر رویداد را در کنسول Google Cloud پیکربندی کنید، اما این شامل رویدادهای کلیک کارت نمیشود. هنگام پیادهسازی تعاملهای کارت، action کارت باید حاوی نشانی وب کامل نقطه پایانی HTTP برای فراخوانی باشد. میتوانید برای هر دکمه یک نقطه پایانی HTTP منحصربهفرد تنظیم کنید، یا از یک نقطه پایانی مشترک استفاده کنید و کنش را بهعنوان پارامتر در action.parameters ارسال کنید.
برای کسب اطلاعات بیشتر، باز کردن کادرهای گفتگوی تعاملی را ببینید. { "onClick": { "action": { "function": "https://...", "parameters": [{ "key": "method", "value": "submit" }] } } } |
برای اطمینان از اینکه تعاملهای کارت برای پیامهای ایجادشده قبلاز تبدیل کار میکند، نشانی وب تعامل کارت را در صفحه پیکربندی «میانای برنامهسازی کاربردی Google Chat» پیکربندی کنید.
این نشانی وب فقط برای تعاملات در پیامهایی که قبلاز تبدیل برنامهتان ایجاد شدهاند استفاده میشود. وقتی کاربری با یکی از این پیامها تعامل میکند، مقدار اصلی action.function بهعنوان پارامتری بهنام __action_method_name__ ارسال میشود.
مثال: کلیک روی کارت
اگر نشانی وب تعامل کارت را بهعنوان https://.../card-interaction-handler پیکربندی کرده باشید و کاربری روی کارتی در پیام قدیمی با کنش زیر کلیک کند:
{
"onClick": {
"action": {
"function": "submit"
}
}
}
رویدادی با قالب زیر به نشانی وب تعامل کارت پیکربندیشده شما ارسال میشود:
{
"commonEventObject": {
"parameters": {
"__action_method_name__": "submit"
}
},
"chat": {
"buttonClickedPayload": { ... }
}
}
مثال: منو چندانتخابی
اگر کاربری با منو چندانتخابی با منبع داده خارجی تعامل داشته باشد:
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"externalDataSource": {
"function": "getContacts"
}
}
}
رویدادی با قالب زیر به نشانی وب تعامل کارت پیکربندیشده شما ارسال میشود:
{
"commonEventObject": {
"parameters": {
"__action_method_name__": "getContacts",
}
},
"chat": {
"widgetUpdatedPayload": { ... }
}
}
اگر استفاده از نشانی وب نقطه پایانی HTTP مشترک برای همه راهاندازها را برای راهاندازهای HTTP خود روشن کنید، نشانی وب مشترک برای رویدادهای کلیک روی دکمه نیز استفاده میشود.
درستیسنجی درخواستهای برافزاهای HTTP Google Workspace که Chat را گسترش میدهند
برای برنامههای Google Chat مبتنی بر HTTP، منطق درستیسنجی اینکه درخواستها از Google سرچشمه میگیرند باید هنگام تبدیل به برافزای Google Workspace بهروز شود.
- درستیسنجی برای برنامههای «گپ HTTP» که برافزا نیستند: درستیسنجی درخواستهای Google Chat
- درستیسنجی HTTP برافزای Google Workspace: درستیسنجی درخواستهای Google
تفاوتهای کلیدی در درستیسنجی درخواست عبارتاند از:
| نوع برنامه | مخاطب پشتیبانیشده | ایمیل حساب سرویس |
|---|---|---|
| برنامه گپی که برافزا نیست | شماره پروژه | chat@system.gserviceaccount.com |
| برافزای Google Workspace که Google Chat را گسترش میدهد | فقط نقطه پایان HTTP | ایمیل حساب سرویس هر پروژه |
نشانی ایمیل حساب خدمات منحصربهفرد برای برافزای Google Workspace شما را میتوانید در بخش تبدیل به برافزاهای Google Workspace در صفحه پیکربندی Google Chat API در کنسول Google Cloud پیدا کنید.
برای درستیسنجی درخواستها در برافزای ارتقایافته Google Workspace:
- اگر از توابع Cloud Run استفاده میکنید، نقش
roles/cloudfunctions.invokerرا به حساب سرویس هر برافزا اعطا کنید. به مجوز دادن دسترسی با IAM مراجعه کنید. - کد درستیسنجی نشان خود را بهروز کنید تا از سرویس برافزای Google Workspace استفاده کنید ایمیل حساب برای درستیسنجی امضای نشان «حامل». به درستیسنجی درخواستهای Google مراجعه کنید.