توضّح هذه الصفحة كيف يمكن لتطبيقات 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
يوضح الجدول التالي الاختلافات وأسباب طلب البحث عن الأحداث أو الاشتراك فيها:
| الاشتراك في الأحداث | طلب بحث للأحداث | |
|---|---|---|
| حالات الاستخدام |
|
|
| 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 البدء في تلقّي أحداث العضوية.
في الشكل 2، يحتوي تطبيق Chat على اشتراك نشط في المساحة، وبالتالي يتلقّى التطبيق حدثًا كلما تغيّرت العضوية في المساحة. يمكن لتطبيق Chat بعد ذلك معالجة أي من الأنشطة أو الرد عليها في الوقت الفعلي، مثل نشر رسالة ترحيب خاصة إلى العضو الذي انضم إلى المساحة.
للتعرّف على كيفية إنشاء الاشتراكات باستخدام Google Workspace Events API، راجِع مستندات واجهة برمجة تطبيقات أحداث Google Workspace.
طلب بحث عن أحداث الاشتراك الأخيرة
وبدلاً من تلقّي أحداث الاشتراك عند وقوعها، يمكن لتطبيق Chat طلب بيانات من Chat API لسرد أحداث المساحة الأخيرة ذات الصلة بنشاط الاشتراك.
في الشكل 3، يستدعي تطبيق في Chat طريقة Chat API
spaces.spaceEvents.list() بعد حدوث كل أنشطة الاشتراك، ويفلتر طلب البحث
لعرض أحداث العضوية الجديدة والمحدَّثة والمحذوفة. تعرض واجهة Chat API
قائمة بمصادر spaceEvent تمثِّل كل تغيير من تغييرات الاشتراك.
ويمكن لتطبيق Chat بعد ذلك المعالجة أو الرد استنادًا إلى الأنشطة الحديثة، مثل نشر رسالة أسبوعية تتضمن ملخصًا لأنشطة الاشتراك في المساحة خلال آخر 7 أيام.
لطلب البحث عن الأحداث باستخدام Chat API، يُرجى الاطّلاع على المقالة إدراج الأحداث من مساحة في Google Chat.
القيود
-
بالنسبة إلى الاشتراكات المخصّصة للمستخدمين، لا يتم بدء الأحداث المتعلّقة بالأعضاء الجدد في الرسائل المباشرة أو المحادثات الجماعية بدون اسم (
google.workspace.chat.membership.v1.created) إلا بعد نشر الرسالة الأولى. - لا تؤدي التغييرات في سجلّ المساحات إلى بدء أحداث المساحة المعدَّلة (نوع الحدث:
google.workspace.chat.spaces.v1.updated). - لتلقّي أحداث العضوية، يجب أن يكون المستخدم عضوًا مباشرًا في المساحة. في حال إضافة مستخدم أو تعديله أو إزالته بشكل غير مباشر إلى مساحة من خلال "مجموعة Google"، لن يتلقّى الاشتراك أحداث الاشتراك هذه. للتعرّف على آلية عمل عضويات "مجموعات Google"، يمكنك الاطّلاع على إضافة مجموعة Google إلى مساحة.
مواضيع ذات صلة
- نظرة عامة على Google Workspace Events API
- إنشاء اشتراك
- الحصول على تفاصيل عن حدث في مساحة Google Chat
- إدراج الأحداث من مساحة في Google Chat
- للحصول على مثال عن كيفية استخدام الأحداث، راجِع الدليل التوجيهي الإجابة عن الأسئلة استنادًا إلى محادثات Chat مع تطبيق Gemini AI Chat.