استخدام الأحداث من Google Chat

توضّح هذه الصفحة كيف يمكن لتطبيقات Google Chat تلقّي الأحداث والردّ عليها في Google Chat.

يمثّل حدث Google Chat نشاطًا أو تغييرًا في Chat، مثل رسالة جديدة في مساحة. يمكن لتطبيق Chat استخدام الأحداث لفهم ما حدث واتّخاذ إجراء أو الردّ بطريقة مفيدة للمستخدمين.

في ما يلي بعض الأمثلة على كيفية استخدام الأحداث:

  • مراقبة الرسائل الجديدة في مساحة والردّ عليها، مثل البحث عن كلمات أو عبارات رئيسية
  • إرسال رسالة ترحيب إلى المستخدمين عند انضمامهم إلى المساحة لشرح إرشادات المساحة أو مشاركة نصائح حول كيفية استخدام تطبيق Chat بفعالية
  • تتبُّع نشاط Chat وتحليله على سبيل المثال، لإرسال تقرير شهري حول الأعضاء الجدد أو الرسائل التي تتلقّى أكبر عدد من التفاعلات أو الردود.
  • التواصل على جميع منصات المراسلة على سبيل المثال، يمكن للمستخدمين إرسال الرسائل وتلقّيها من مستخدمين على منصة مراسلة مختلفة بدون مغادرة Chat.

طريقة عمل الأحداث

عند حدوث أي شيء في Google Chat، يتم إنشاء مورد Google Chat API أو تعديله أو حذفه. يستخدم Chat الأحداث لتقديم معلومات إلى تطبيق Chat حول نوع النشاط الذي حدث ومورد Chat API المتأثر.

مثال على كيفية بدء حدث عند نشر رسالة في مساحة Google Chat
الشكل 1. ينشر أحد المستخدمين رسالة في مساحة Chat، ما يؤدي إلى إنشاء مورد Message. بعد ذلك، ينشئ Chat حدثًا يتضمّن بيانات حول الرسالة الجديدة.

يصنّف Chat الأحداث حسب النوع. تساعدك أنواع الأحداث في فلترة المعلومات وتلقّي النوع الذي تحتاجه فقط، كما تتيح لك التعامل مع الأنشطة المشابهة بالطريقة نفسها.

يوضّح الجدول التالي كيف يؤثّر نشاط في Chat على مصدر ذي صلة في Chat API، ونوع الحدث الذي يتلقّاه تطبيق Chat:

النشاط مصدر Chat API نوع الحدث
ينشر مستخدم رسالة في مساحة Chat يتم إنشاء مورد Message. رسالة جديدة
يصبح المستخدم مدير مساحة. تم تعديل مورد Membership. تم تعديل العضوية
يتفاعل مستخدم مع رسالة. يتم إنشاء مورد Reaction. تفاعل جديد
يغادر مستخدم مساحة. تم حذف مرجع Membership. العضوية المحذوفة

تلقّي أحداث من Google Chat

لتلقّي الأحداث، يمكن لتطبيق Chat إجراء أيّ مما يلي:

  • يمكنك الاشتراك في الأحداث باستخدام "واجهة برمجة تطبيقات أحداث Google Workspace" لتلقّي الأحداث فور حدوثها.
  • يمكنك طلب الأحداث الأخيرة من خلال الاتصال بواجهة برمجة تطبيقات Chat.

يوضّح الجدول التالي الفرق بين طلب البحث عن الأحداث أو الاشتراك فيها وأسباب ذلك:

الاشتراك في الأحداث طلب البحث عن الأحداث
حالات الاستخدام
  • معالجة الأحداث أو الردّ عليها في الوقت الفعلي
  • يمكنك مراقبة نشاط المستخدمين في العضوية واكتشاف مساحات جديدة لمراقبتها.
  • معالجة الأحداث أو الردّ عليها بشكل دوري أو من خلال مشغّل
  • استرداد الأحداث الفائتة من اشتراك (بسبب انقطاع الخدمة أو عدم نشاط الاشتراك)
واجهة برمجة التطبيقات واجهة برمجة التطبيقات لفعاليات Google Workspace واجهة برمجة التطبيقات للدردشة
مصدر الأحداث المساحات والمستخدمون المساحات فقط
الأحداث المتوافقة
  • الرسائل
  • العضويات
  • التفاعلات
  • مسافة

للحصول على قائمة بأنواع الأحداث المتوافقة، يُرجى الاطّلاع على أنواع الأحداث لإنشاء الاشتراكات في مستندات "واجهة برمجة تطبيقات أحداث Google Workspace".
  • الرسائل
  • العضويات
  • التفاعلات
  • مسافة

للاطّلاع على قائمة بأنواع الأحداث المتوافقة، يُرجى الرجوع إلى المرجع spaceEvents في مستندات مرجع Chat API.
تنسيق الحدث رسالة Google Cloud Pub/Sub منسَّقة وفقًا لمواصفات CloudEvent لمزيد من التفاصيل، يُرجى الاطّلاع على بنية أحداث Google Workspace. أحد موارد Chat API ( spaces.spaceEvent)
بيانات الأحداث سلسلة مرمّزة باستخدام Base64 تتضمّن بيانات المورد أو لا تتضمّنها للاطّلاع على أمثلة للحِزم، راجِع بيانات الأحداث. حِمل JSON يحتوي على بيانات الموارد تتضمّن بعض أنواع الأحداث حقول موارد معيّنة فقط. للاطّلاع على أمثلة للحِزم، يُرجى الرجوع إلى المستندات المرجعية.

مثال: طلب أو الاشتراك في أحداث حول العضويات في مساحة

في هذا المثال، يطلب تطبيق Chat تلقّي معلومات حول التغييرات التي تطرأ على أعضاء مساحة في Chat. في المساحة، يحدث نشاط العضوية التالي:

  • ينضم مستخدم إلى المساحة، ما يؤدي إلى إنشاء مورد Membership وتشغيل حدث عضو جديد.
  • يصبح المستخدم مدير مساحة، ما يؤدي إلى تعديل المورد Membership الخاص بالمستخدم وتشغيل حدث عضو معدَّل.
  • يغادر المستخدم المساحة، ما يؤدي إلى حذف المورد Membership الخاص بالمستخدم وتفعيل حدث "تم حذف عضو".

الاشتراك في أحداث العضوية

لتلقّي الأحداث في الوقت الفعلي، يستدعي تطبيق Chat طريقة subscriptions.create() في Google Workspace Events API للاشتراك في المساحة لجميع أنواع أحداث العضوية. بعد إنشاء الاشتراك، يمكن لتطبيق Chat البدء في تلقّي أحداث العضوية.

تطبيق Chat يشترك في الأحداث باستخدام Google Workspace Events API.
الشكل 2. يتلقّى تطبيق Chat أحداث العضوية من خلال اشتراك باستخدام Google Workspace Events API.

في الشكل 2، يتضمّن تطبيق Chat اشتراكًا نشطًا في المساحة، وبالتالي يتلقّى التطبيق حدثًا كلما تغيّرت عضوية في المساحة. يمكن لتطبيق Chat بعد ذلك معالجة أي من الأنشطة أو الرد عليها في الوقت الفعلي، مثل نشر رسالة ترحيب خاصة للعضو الذي انضم إلى المساحة.

للتعرّف على كيفية إنشاء اشتراكات باستخدام "واجهة برمجة تطبيقات أحداث Google Workspace"، راجِع مستندات "واجهة برمجة تطبيقات أحداث Google Workspace".

طلب البحث عن أحداث العضوية الأخيرة

بدلاً من تلقّي أحداث العضوية فور حدوثها، يمكن لتطبيق Chat استدعاء Chat API لعرض قائمة بأحداث المساحة الحديثة المرتبطة بنشاط العضوية.

تطبيق Chat يطلب بيانات الأحداث باستخدام Chat API.
الشكل 3. يتلقّى تطبيق Chat أحداث الاشتراك الحديثة من خلال طلب البحث عن أحداث المساحة باستخدام Chat API.

في الشكل 3، يستدعي تطبيق Chat طريقة spaces.spaceEvents.list() في Chat API بعد حدوث جميع أنشطة العضوية، ويتم فلترة طلب البحث للعثور على أحداث العضوية الجديدة والمعدَّلة والمحذوفة. تعرض Chat API قائمة بموارد spaceEvent تمثّل كل تغيير من تغييرات العضوية. يمكن لتطبيق Chat بعد ذلك معالجة النشاط الأخير أو الردّ عليه، مثل نشر رسالة أسبوعية تتضمّن ملخّصًا لنشاط أعضاء المساحة خلال الأيام السبعة الماضية.

لإجراء طلب بحث عن الأحداث باستخدام Chat API، يُرجى الاطّلاع على إدراج الأحداث من مساحة في Google Chat.

القيود
  • بالنسبة إلى الاشتراكات في المستخدمين، لا يتم تشغيل الأحداث المتعلقة بالأعضاء الجدد في الرسائل المباشرة أو المحادثات الجماعية بدون اسم (google.workspace.chat.membership.v1.created) إلا بعد نشر الرسالة الأولى.
  • لتلقّي أحداث العضوية، يجب أن يكون المستخدم عضوًا مباشرًا في المساحة. إذا تمت إضافة مستخدم أو تعديله أو إزالته بشكل غير مباشر إلى مساحة من خلال "مجموعة Google"، لن يتلقّى الاشتراك أحداث العضوية هذه. للتعرّف على طريقة عمل عضويات "مجموعة Google"، يُرجى الاطّلاع على إضافة "مجموعة Google" إلى مساحة.