این صفحه توضیح می‌دهد که برنامه‌های Google Chat چگونه می‌توانند رویدادها را در Google Chat دریافت کنند و به آن‌ها پاسخ دهند.
رویداد Google Chat نشان‌دهنده فعالیت یا تغییر در Chat است، مانند پیام جدید در فضا. برنامه Chat شما می‌تواند از رویدادها برای درک آنچه اتفاق افتاده است استفاده کند و اقدام کند یا به روشی معنادار برای کاربران شما پاسخ دهد.
در اینجا چند نمونه از نحوه استفاده از رویدادها آورده شده است:
- پایش و پاسخ دادن به پیام‌های جدید در فضا، مثل بررسی کردن کلیدواژه‌ها یا عبارت‌ها.
- هنگام پیوستن کاربران به فضا، پیام خوشامدگویی برای آن‌ها ارسال کنید تا دستورالعمل‌های فضا را توضیح دهید یا نکاتی درباره نحوه استفاده مؤثر از برنامه Chat هم‌رسانی کنید.
- فعالیت Chat را پیگیری و تحلیل کنید. برای مثال، برای ارسال گزارش ماهانه درباره اعضای جدید یا پیام‌هایی که بیشترین واکنش یا پاسخ را دریافت می‌کنند.
- در پلاتفرم‌های پیام‌رسانی مختلف ارتباط برقرار کنید. برای مثال، کاربران می‌توانند بدون ترک کردن Chat، از کاربران پلاتفرم پیام‌رسانی دیگری پیام ارسال و دریافت کنند.
نحوه عملکرد رویدادها
هرگاه اتفاقی در Google Chat رخ دهد، یک منبع Google Chat API ایجاد، به‌روزرسانی، یا حذف می‌شود. Chat از رویدادها برای ارائه اطلاعات به برنامه Chat شما درباره نوع فعالیتی که رخ داده است و منبع Chat API که تحت‌تأثیر قرار گرفته است استفاده می‌کند.
Message را ایجاد می‌کند.
Chat سپس رویدادی ایجاد می‌کند که حاوی داده‌های مربوط به پیام جدید است.Chat رویدادها را براساس نوع دسته‌بندی می‌کند. انواع رویداد به شما کمک می‌کند فیلتر کنید و فقط نوع اطلاعاتی را که نیاز دارید دریافت کنید، و به شما امکان می‌دهد فعالیت‌های مشابه را به روشی یکسان مدیریت کنید.
جدول زیر نشان می‌دهد که چگونه یک فعالیت در Chat بر یک منبع مرتبط Chat API تأثیر می‌گذارد و نوع رویدادی که برنامه Chat شما دریافت می‌کند:
| فعالیت | منبع Chat API | نوع رویداد |
|---|---|---|
| کاربری در فضای Chat پیامی پست می‌کند | منبع Message ایجاد شده است. |
پیام جدید |
| کاربری مدیر فضا می‌شود. | منبع Membership به‌روزرسانی شده است. |
عضویت به‌روزرسانی‌شده |
| کاربری به پیامی واکنش نشان می‌دهد. | منبع Reaction ایجاد شده است. |
واکنش جدید |
| کاربری فضا را ترک کند. | منبع Membership حذف شده است. |
عضویت حذف شد |
دریافت رویدادها از Google Chat
برای دریافت رویدادها، برنامه Chat شما می‌تواند یکی از کارهای زیر را انجام دهد:
- بااستفاده از Google Workspace Events API در رویدادها مشترک شوید تا رویدادها را به‌محض وقوع دریافت کنید.
- با فراخوانی Chat API، رویدادهای اخیر را جستجو کنید.
جدول زیر تفاوت و دلایل پرسمان یا مشترک شدن در رویدادها را توضیح می‌دهد:
| مشترک شدن در رویدادها | پرس‌وجو برای رویدادها | |
|---|---|---|
| موارد استفاده |
|
|
| میانای برنامه‌سازی کاربردی | Google Workspace Events API | Chat API |
| منبع رویدادها | فضاها، کاربران، و سازمان‌های Google Workspace ( پیش‌نمای توسعه‌دهندگان نرم‌افزار) | فقط فضاها |
| رویدادهای پشتیبانی‌شده |
برای مشاهده فهرست انواع رویدادهای پشتیبانی‌شده، به انواع رویداد برای ایجاد اشتراک در سند Google Workspace Events API مراجعه کنید. |
برای مشاهده فهرست انواع رویدادهای پشتیبانی‌شده، به منبع spaceEvents در سند مرجع Chat API
مراجعه کنید.
|
| قالب رویداد | پیام Google Cloud Pub/Sub، قالب‌بندی‌شده طبق مشخصات CloudEvent. برای جزئیات، ساختار رویدادهای Google Workspace را ببینید. |
منبع Chat API
(
spaces.spaceEvent)
|
| داده‌های رویداد | رشته کدبندی‌شده Base64 با یا بدون داده‌های منبع. برای نمونه‌های بار مفید، به داده‌های رویداد مراجعه کنید. | پایه‌بار JSON که حاوی داده‌های منبع است. برخی‌از انواع رویداد فقط شامل فیلدهای منبع خاصی می‌شوند. برای مثال‌های بار داده، اسناد مرجع را ببینید. |
مثال: پرسمان یا مشترک شدن در رویدادهای مربوط به عضویت‌ها در فضا
در این مثال، برنامه Chat می‌خواهد اطلاعاتی درباره تغییرات اعضای فضای Chat دریافت کند. در فضا، فعالیت عضویت زیر رخ می‌دهد:
- کاربری به فضا می‌پیوندد که این کار منبع
Membershipرا ایجاد می‌کند و رویداد عضو جدید را راه‌اندازی می‌کند. - کاربری مدیر فضا می‌شود، که منبع
Membershipرا برای کاربر به‌روز می‌کند و رویداد عضو به‌روزشده را راه‌اندازی می‌کند. - کاربری فضا را ترک می‌کند، که باعث حذف منبع
Membershipبرای کاربر می‌شود و رویداد حذف عضو را راه‌اندازی می‌کند.
مشترک شدن در رویدادهای عضویت
برای دریافت رویدادها در زمان واقعی،
برنامه Chat روش Google Workspace Events API
subscriptions.create()
را برای مشترک شدن در فضا برای همه انواع رویدادهای عضویت فراخوانی می‌کند. پس‌از
ایجاد اشتراک، برنامه Chat می‌تواند
رویدادهای عضویت را دریافت کند.
در شکل ۲، برنامه Chat اشتراک فعالی در فضا دارد، بنابراین هرگاه عضویت در فضا تغییر کند، برنامه رویدادی دریافت می‌کند. سپس برنامه Chat می‌تواند هریک از فعالیت‌ها را به‌طور هم‌زمان پردازش کند یا به آن‌ها پاسخ دهد، مثلاً پست کردن پیام خوشامدگویی خصوصی برای عضوی که به فضا پیوسته است.
برای آشنایی با ایجاد اشتراک بااستفاده از Google Workspace Events API، به سند Google Workspace Events API مراجعه کنید.
پرس‌وجو برای رویدادهای اخیر عضویت
به‌جای دریافت رویدادهای عضویت به‌محض وقوع، برنامه Chat می‌تواند Chat API را برای فهرست کردن رویدادهای اخیر فضا که مربوط به فعالیت عضویت است فراخوانی کند.
در شکل ۳، برنامه Chat پس‌از وقوع همه فعالیت‌های عضویت، روش
spaces.spaceEvents.list()
Chat API را فراخوانی می‌کند و پُرسمان را برای رویدادهای عضویت جدید، به‌روزشده، و حذف‌شده فیلتر می‌کند. Chat API
فهرستی از منابع spaceEvent را برمی‌گرداند که هرکدام از تغییرات عضویت را نشان می‌دهد.
سپس برنامه Chat می‌تواند براساس فعالیت اخیر پردازش یا پاسخ دهد، مثلاً پست کردن پیام هفتگی با خلاصه‌ای از فعالیت عضویت فضا در ۷ روز گذشته.
برای پُرسمان رویدادها بااستفاده از Chat API، فهرست کردن رویدادها از فضای Google Chat را ببینید.
محدودیت‌ها و رفتارهای تحویل
محدودیت‌های عمومی
- برای دریافت رویدادهای عضویت، کاربر یا برنامه Chat باید عضو مستقیم فضا باشد. اگر به‌طور غیرمستقیم ازطریق «گروه Google» به فضایی اضافه، به‌روزرسانی، یا برداشته شده باشند، اشتراک آن رویدادهای عضویت را دریافت نمی‌کند. برای درک نحوه عملکرد عضویت در «گروه Google»، افزودن «گروه Google» به فضا را ببینید.
اشتراک‌های کاربر
-
برای اشتراک‌های کاربران، رویدادهای مربوط به اعضای جدید در پیام‌های مستقیم یا گپ‌های گروهی بی‌نام (
google.workspace.chat.membership.v1.created)، فقط پس‌از پست شدن اولین پیام راه‌اندازی می‌شوند.
اشتراک‌های مشتری
برای اشتراک‌های مشتری، محدودیت‌های زیر اعمال می‌شود:
- سازمان Google Workspace باید حداقل یک پروانه «واحد نگهداری موجودی» Enterprise داشته باشد.
- برنامه Chat فقط می‌تواند یک اشتراک مشتری برای سازمان Google Workspace مشخص ایجاد کند. یک سازمان Google Workspace می‌تواند درمجموع حداکثر پنج اشتراک مشتری (ایجادشده توسط برنامه‌های Chat مختلف) داشته باشد.
برای اشتراک‌های مشتری، تحویل رویداد از این قوانین کلی پیروی می‌کند:
- رویدادهای فضا: فقط درصورتی ارسال می‌شود که رویداد در فضایی که توسط سازمان Google Workspace شما مدیریت می‌شود رخ دهد.
- رویدادهای کاربر: فقط درصورتی ارسال می‌شود که رویداد برای کاربری اتفاق بیفتد که به سازمان Google Workspace شما تعلق دارد.
تنها استثنای این قوانین برای رویدادهای عضویت است. اشتراکتان می‌تواند رویدادهای عضویت را هم از فضاهای تحت مدیریت سازمانتان و هم از فضاهای تحت مدیریت سازمان‌های خارجی دریافت کند، اما نحوه تحویل آن‌ها به این بستگی دارد که کدام سازمان فضا را مدیریت می‌کند:
فضاهایی که توسط سازمان Google Workspace شما مدیریت می‌شود
اگر تغییری در عضویت در فضایی که توسط سازمان Google Workspace مدیریت می‌شود رخ دهد، به‌عنوان رویداد فضا ارائه می‌شود.
نام منبع رویداد فضا از قالب زیر استفاده می‌کند:
spaces/{spaceId}/spaceEvents/{spaceEventId}
فضاهایی که توسط سازمان‌های خارجی مدیریت می‌شوند
اگر عضویت کاربری که توسط سازمان Google Workspace شما مدیریت می‌شود در فضایی که توسط سازمان خارجی مدیریت می‌شود (برای مثال، فضای خارجی نام‌گذاری‌شده یا پیام مستقیمی که توسط کاربر خارجی ایجاد شده است) تغییر کند، اشتراک شما این رویداد را به‌عنوان رویداد کاربر دریافت می‌کند.
نام منبع رویداد کاربر از قالب زیر استفاده می‌کند:
users/{userId}/userEvents/{userEventId}