این صفحه توضیح می‌دهد که چگونه برنامه‌های Google Chat می‌توانند رویدادها را در Google Chat دریافت کرده و به آنها پاسخ دهند.
یک رویداد گوگل چت نشان‌دهنده یک فعالیت یا تغییر در چت است، مانند یک پیام جدید در یک فضا. برنامه چت شما می‌تواند از رویدادها برای درک آنچه اتفاق افتاده است و اقدام یا پاسخی معنادار برای کاربران شما انجام دهد.
در اینجا چند مثال از نحوه استفاده از رویدادها آورده شده است:
- پیام‌های جدید در یک فضا را رصد کنید و به آنها پاسخ دهید، مانند بررسی کلمات یا عبارات کلیدی.
- هنگام ورود کاربران به فضا، یک پیام خوشامدگویی برای آنها ارسال کنید تا دستورالعمل‌های فضا را توضیح دهید یا نکاتی در مورد نحوه استفاده مؤثر از برنامه چت به اشتراک بگذارید.
- فعالیت چت را پیگیری و تجزیه و تحلیل کنید. به عنوان مثال، برای ارسال گزارش ماهانه در مورد اعضای جدید یا پیام‌هایی که بیشترین واکنش یا پاسخ را دریافت می‌کنند.
- ارتباط بین پلتفرم‌های پیام‌رسان. به عنوان مثال، کاربران می‌توانند بدون ترک چت، پیام‌هایی را از کاربران یک پلتفرم پیام‌رسان دیگر ارسال و دریافت کنند.
نحوه عملکرد رویدادها
هر زمان که اتفاقی در گوگل چت رخ می‌دهد، یک منبع API گوگل چت ایجاد، به‌روزرسانی یا حذف می‌شود. چت از رویدادها برای ارائه اطلاعات به برنامه چت شما در مورد نوع فعالیت رخ داده و منبع API چت که تحت تأثیر قرار گرفته است، استفاده می‌کند.
Message می‌شود. سپس چت رویدادی ایجاد می‌کند که حاوی داده‌هایی در مورد پیام جدید است.چت رویدادها را بر اساس نوع دسته‌بندی می‌کند. انواع رویدادها به شما کمک می‌کنند تا فقط نوع اطلاعات مورد نیاز خود را فیلتر و دریافت کنید و به شما امکان می‌دهد فعالیت‌های مشابه را به یک روش انجام دهید.
جدول زیر نشان می‌دهد که چگونه یک فعالیت در Chat بر یک منبع API چت مرتبط تأثیر می‌گذارد و نوع رویدادی که برنامه Chat شما دریافت می‌کند را نشان می‌دهد:
| فعالیت | منبع API چت | نوع رویداد |
|---|---|---|
| یک کاربر در فضای چت پیامی ارسال می‌کند | یک منبع Message ایجاد می‌شود. | پیام جدید |
| یک کاربر مدیر فضا می‌شود. | منبع Membership به‌روزرسانی شده است. | عضویت به‌روزرسانی‌شده |
| کاربر به یک پیام واکنش نشان می‌دهد. | یک منبع Reaction ) ایجاد می‌شود. | واکنش جدید |
| کاربر یک فاصله ایجاد می‌کند. | یک منبع Membership حذف شده است. | عضویت حذف شده |
دریافت رویدادها از گوگل چت
برای دریافت رویدادها، برنامه چت شما می‌تواند یکی از موارد زیر را انجام دهد:
- با استفاده از رابط برنامه‌نویسی کاربردی رویدادهای فضای کاری گوگل (Google Workspace Events API) در رویدادها مشترک شوید تا رویدادها را به محض وقوع دریافت کنید.
- با فراخوانی Chat API، رویدادهای اخیر را جستجو کنید.
جدول زیر تفاوت و دلایل پرس‌وجو یا عضویت در رویدادها را توضیح می‌دهد:
| اشتراک در رویدادها | پرس و جو برای رویدادها | |
|---|---|---|
| موارد استفاده |
|
|
| رابط برنامه‌نویسی کاربردی | رابط برنامه‌نویسی کاربردی رویدادهای فضای کاری گوگل (Google Workspace Events API) | API چت |
| منبع رویدادها | فضاها و کاربران | فقط فضاها |
| رویدادهای پشتیبانی شده |
برای مشاهده فهرستی از انواع رویدادهای پشتیبانی‌شده، به بخش انواع رویدادها برای ایجاد اشتراک‌ها در مستندات Google Workspace Events API مراجعه کنید. |
برای فهرستی از انواع رویدادهای پشتیبانی‌شده، به منبع spaceEvents در مستندات مرجع Chat API مراجعه کنید. |
| قالب رویداد | یک پیام Google Cloud Pub/Sub، که طبق مشخصات CloudEvent قالب‌بندی شده است. برای جزئیات بیشتر، به ساختار رویدادهای Google Workspace مراجعه کنید. | یک منبع API چت ( spaces.spaceEvent ) |
| داده‌های رویداد | رشته کدگذاری شده با Base64 با یا بدون داده‌های منبع. برای مثال، payloadها، به Event data مراجعه کنید. | بار داده JSON که شامل داده‌های منبع است. برخی از انواع رویدادها فقط شامل فیلدهای منبع خاصی هستند. برای مثال، به مستندات مرجع مراجعه کنید. |
مثال: درخواست یا اشتراک در رویدادهای مربوط به عضویت در یک فضا
در این مثال، یک برنامه چت می‌خواهد اطلاعاتی در مورد تغییرات اعضای یک فضای چت دریافت کند. در این فضا، فعالیت عضویت زیر رخ می‌دهد:
- یک کاربر به فضا می‌پیوندد که یک منبع
Membershipایجاد می‌کند و یک رویداد عضویت جدید را فعال می‌کند. - یک کاربر به مدیر فضا تبدیل می‌شود که منبع
Membershipرا برای کاربر به‌روزرسانی می‌کند و یک رویداد به‌روزرسانی‌شده‌ی عضو را فعال می‌کند. - کاربر از فضا خارج می‌شود که باعث حذف منبع
Membershipبرای کاربر و فعال شدن رویداد حذف عضو می‌شود.
در رویدادهای عضویت مشترک شوید
برای دریافت رویدادها به صورت بلادرنگ، برنامه چت متد subscriptions.create() از API رویدادهای فضای کاری گوگل را فراخوانی می‌کند تا در فضا برای انواع رویدادهای عضویت مشترک شود. پس از ایجاد اشتراک، برنامه چت می‌تواند شروع به دریافت رویدادهای عضویت کند.
در شکل ۲، برنامه چت یک اشتراک فعال در این فضا دارد، بنابراین هر زمان که عضویت در این فضا تغییر کند، برنامه یک رویداد دریافت می‌کند. سپس برنامه چت می‌تواند هر یک از فعالیت‌ها، مانند ارسال پیام خوشامدگویی خصوصی به عضوی که به این فضا پیوسته است را به صورت بلادرنگ پردازش یا پاسخ دهد.
برای کسب اطلاعات بیشتر در مورد ایجاد اشتراک با استفاده از Google Workspace Events API، به مستندات Google Workspace Events API مراجعه کنید.
جستجوی رویدادهای عضویت اخیر
به جای دریافت رویدادهای عضویت به محض وقوع، یک برنامه چت می‌تواند API چت را فراخوانی کند تا رویدادهای فضایی اخیر مرتبط با فعالیت عضویت را فهرست کند.
در شکل 3، یک برنامه چت، متد spaces.spaceEvents.list() از API چت را پس از وقوع تمام فعالیت‌های عضویت فراخوانی می‌کند و پرس‌وجو را برای رویدادهای عضویت جدید، به‌روزرسانی‌شده و حذف‌شده فیلتر می‌کند. API چت فهرستی از منابع spaceEvent را برمی‌گرداند که نشان‌دهنده هر یک از تغییرات عضویت است. سپس برنامه چت می‌تواند بر اساس فعالیت اخیر، مانند ارسال یک پیام هفتگی با خلاصه‌ای از فعالیت عضویت فضا در 7 روز گذشته، پردازش یا پاسخ دهد.
برای جستجوی رویدادها با استفاده از API چت، به فهرست کردن رویدادها از فضای چت گوگل مراجعه کنید.
محدودیت‌ها
- برای اشتراک کاربران، رویدادهای مربوط به اعضای جدید در پیام‌های مستقیم یا چت‌های گروهی بدون نام (
google.workspace.chat.membership.v1.created)، فقط پس از ارسال اولین پیام فعال می‌شوند. - برای دریافت رویدادهای عضویت، کاربر یا برنامه چت باید عضو مستقیم آن فضا باشند. اگر آنها به طور غیرمستقیم از طریق یک گروه گوگل به یک فضا اضافه، به‌روزرسانی یا حذف شده باشند، اشتراک آن رویدادهای عضویت را دریافت نمی‌کند. برای درک نحوه عملکرد عضویت در گروه گوگل، به افزودن یک گروه گوگل به یک فضا مراجعه کنید.
مباحث مرتبط
- مرور کلی API رویدادهای Google Workspace
- ایجاد اشتراک
- جزئیات مربوط به یک رویداد فضایی Google Chat را دریافت کنید
- رویدادها را از یک فضای چت گوگل فهرست کنید