با رویدادهای Google Chat کار کنید

این صفحه توضیح می‌دهد که چگونه برنامه‌های چت Google می‌توانند رویدادها را در Google Chat دریافت کرده و به آنها پاسخ دهند.

رویداد گپ Google نشان دهنده یک فعالیت یا تغییر در چت است، مانند یک پیام جدید در یک فضا. برنامه گپ شما می تواند از رویدادها برای درک آنچه اتفاق افتاده است استفاده کند و اقدام کند یا به روشی معنادار برای کاربران شما پاسخ دهد.

در اینجا چند نمونه از نحوه استفاده از رویدادها آورده شده است:

  • پیام‌های جدید را در یک فضا نظارت کنید و به آنها پاسخ دهید، مانند بررسی کلمات یا عبارات کلیدی.
  • هنگام پیوستن به فضا، پیام خوشامدگویی را برای کاربران ارسال کنید تا دستورالعمل‌های فضا را توضیح دهند یا نکاتی را درباره نحوه استفاده مؤثر از برنامه چت به اشتراک بگذارند.
  • پیگیری و تجزیه و تحلیل فعالیت چت. به عنوان مثال، برای ارسال گزارش ماهانه در مورد اعضای جدید یا پیام هایی که بیشترین واکنش ها یا پاسخ ها را دریافت می کنند.
  • در پلتفرم های پیام رسانی ارتباط برقرار کنید. به عنوان مثال، کاربران می توانند بدون خروج از چت، پیام هایی را از کاربران در یک پلت فرم پیام رسانی متفاوت ارسال و دریافت کنند.

رویدادها چگونه کار می کنند

هر زمان که در Google Chat اتفاقی بیفتد، یک منبع Google Chat API ایجاد، به‌روزرسانی یا حذف می‌شود. Chat از رویدادها برای ارائه اطلاعات به برنامه Chat شما در مورد نوع فعالیت رخ داده و منبع Chat API که تحت تأثیر قرار گرفته است استفاده می کند.

مثالی از اینکه چگونه یک پیام پست شده در فضای چت Google یک رویداد را راه اندازی می کند.
شکل 1. یک کاربر پیامی را در فضای چت ارسال می کند که یک منبع Message ایجاد می کند. سپس Chat رویدادی ایجاد می‌کند که حاوی داده‌هایی درباره پیام جدید است.

چت رویدادها را بر اساس نوع دسته بندی می کند. انواع رویداد به شما کمک می کند تا تنها نوع اطلاعاتی را که نیاز دارید فیلتر کرده و دریافت کنید و به شما امکان می دهد فعالیت های مشابه را به همان روش انجام دهید.

جدول زیر نشان می‌دهد که چگونه یک فعالیت در Chat بر منبع Chat API مرتبط تأثیر می‌گذارد و نوع رویدادی که برنامه Chat شما دریافت می‌کند:

فعالیت منبع Chat API نوع رویداد
یک کاربر پیامی را در فضای چت ارسال می کند یک منبع Message ایجاد می شود. پیام جدید
یک کاربر مدیر فضا می شود. یک منبع Membership به روز می شود. عضویت به روز شد
کاربر به یک پیام واکنش نشان می دهد. یک منبع Reaction ایجاد می شود. واکنش جدید
کاربر فضایی را ترک می کند. یک منبع Membership حذف شده است. عضویت حذف شده

رویدادها را از چت Google دریافت کنید

برای دریافت رویدادها، برنامه چت شما می‌تواند یکی از کارهای زیر را انجام دهد:

  • با استفاده از Google Workspace Events API در رویدادها مشترک شوید تا رویدادها را هنگام وقوع دریافت کنید.
  • رویدادهای اخیر را با تماس با Chat API جستجو کنید.

جدول زیر تفاوت و دلایل پرس و جو یا اشتراک در رویدادها را توضیح می دهد:

اشتراک در رویدادها پرس و جو برای رویدادها
موارد استفاده کنید
  • رویدادها را در زمان واقعی پردازش یا پاسخ دهید.
  • نظارت بر فعالیت عضویت کاربران و کشف فضاهای جدید برای نظارت.
  • رویدادها را به صورت دوره ای یا از طریق یک محرک پردازش یا پاسخ دهید.
  • رویدادهای از دست رفته را از اشتراک (به دلیل قطع یا غیرفعال بودن اشتراک) واکشی کنید.
API Google Workspace Events API Chat API
منبع حوادث فضاها و کاربران فقط فضاها
رویدادهای پشتیبانی شده
  • پیام ها
  • عضویت ها
  • واکنش ها
  • فضا

برای فهرستی از انواع رویدادهای پشتیبانی شده، انواع رویداد برای ایجاد اشتراک در اسناد Google Workspace Events API را ببینید.
  • پیام ها
  • عضویت ها
  • واکنش ها
  • فضا

برای لیستی از انواع رویدادهای پشتیبانی شده، به منبع spaceEvents در مستندات مرجع Chat API مراجعه کنید.
قالب رویداد یک پیام Google Cloud Pub/Sub که بر اساس مشخصات CloudEvent قالب‌بندی شده است. برای جزئیات، به ساختار رویدادهای Google Workspace مراجعه کنید. یک منبع Chat API ( spaces.spaceEvent )
داده های رویداد رشته کدگذاری شده با Base64 با یا بدون داده منبع. برای مثال محموله‌ها، داده‌های رویداد را ببینید. بار JSON که حاوی داده های منبع است. برخی از انواع رویدادها فقط شامل فیلدهای منبع خاصی هستند. برای مثال محموله‌ها، به مستندات مرجع مراجعه کنید.

مثال: رویدادهای مربوط به عضویت در یک فضا را پرس و جو کنید یا در آن مشترک شوید

در این مثال، یک برنامه چت می خواهد اطلاعاتی درباره تغییرات اعضای یک فضای چت دریافت کند. در فضا، فعالیت عضویت زیر رخ می دهد:

  • کاربر به فضا می‌پیوندد که یک منبع Membership ایجاد می‌کند و یک رویداد عضو جدید را راه‌اندازی می‌کند.
  • یک کاربر مدیر فضایی می شود که منبع Membership را برای کاربر به روز می کند و یک رویداد عضو به روز را راه اندازی می کند.
  • کاربر فضا را ترک می‌کند، که منبع Membership کاربر را حذف می‌کند و رویداد حذف شده عضو را راه‌اندازی می‌کند.

در رویدادهای عضویت مشترک شوید

برای دریافت رویدادها در زمان واقعی، برنامه Chat متد Google Workspace Events API subscriptions.create() را فراخوانی می‌کند تا در فضا برای همه انواع رویدادهای عضویت مشترک شود. پس از ایجاد اشتراک، برنامه چت می تواند شروع به دریافت رویدادهای عضویت کند.

برنامه چت که مشترک رویدادها با استفاده از Google Workspace Events API.
شکل 2. یک برنامه چت رویدادهای عضویت را از طریق اشتراک با استفاده از Google Workspace Events API دریافت می کند.

در شکل 2، برنامه چت یک اشتراک فعال در فضا دارد، بنابراین هر زمان که عضویت در فضا تغییر کند، برنامه یک رویداد دریافت می کند. سپس برنامه چت می‌تواند هر یک از فعالیت‌ها را پردازش کند یا در زمان واقعی به آن پاسخ دهد، مانند ارسال یک پیام خوشامدگویی خصوصی برای عضوی که به فضا پیوسته است.

برای آشنایی با ایجاد اشتراک با استفاده از Google Workspace Events API، به مستندات Google Workspace Events API مراجعه کنید.

پرس و جو برای رویدادهای عضویت اخیر

به جای دریافت رویدادهای عضویت در حین وقوع، یک برنامه چت می‌تواند با Chat API تماس بگیرد تا رویدادهای فضایی اخیر مرتبط با فعالیت عضویت را فهرست کند.

برنامه چت که برای رویدادها با استفاده از Chat API.
شکل 3. یک برنامه چت رویدادهای عضویت اخیر را با پرس و جو برای رویدادهای فضایی با استفاده از Chat API دریافت می کند.

در شکل 3، یک برنامه چت، متد Chat API spaces.spaceEvents.list() را پس از انجام تمام فعالیت های عضویت فراخوانی می کند و پرس و جو را برای رویدادهای عضویت جدید، به روز شده و حذف شده فیلتر می کند. Chat API فهرستی از منابع spaceEvent را برمی‌گرداند که هر یک از تغییرات عضویت را نشان می‌دهند. سپس برنامه چت می‌تواند بر اساس فعالیت اخیر، مانند ارسال یک پیام هفتگی با خلاصه‌ای از فعالیت عضویت فضا در 7 روز گذشته، پردازش یا پاسخ دهد.

برای درخواست رویدادها با استفاده از Chat API، به فهرست رویدادها از فضای گپ Google مراجعه کنید.

محدودیت ها

  • برای اشتراک‌های کاربران، رویدادهای مربوط به اعضای جدید در پیام‌های مستقیم یا چت‌های گروهی بدون نام ( google.workspace.chat.membership.v1.created )، فقط پس از پست شدن اولین پیام فعال می‌شوند.
  • برای دریافت رویدادهای عضویت، کاربر باید عضو مستقیم فضا باشد. اگر کاربری به‌طور غیرمستقیم از طریق یک گروه Google به فضایی اضافه، به‌روزرسانی یا حذف شده باشد، اشتراک آن رویدادهای عضویت را دریافت نمی‌کند. برای درک نحوه عملکرد عضویت در گروه Google، به افزودن یک گروه Google به یک فضا مراجعه کنید.