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

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

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

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

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

آلية عمل الأحداث

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

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

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

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

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

لتلقّي الأحداث، يمكن لتطبيق Chat تنفيذ أيّ مما يلي:

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

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

	الاشتراك في الأحداث	طلب الأحداث
حالات الاستخدام	معالجة الأحداث أو الردّ عليها في الوقت الفعلي مراقبة نشاط الاشتراكات لدى المستخدمين واستكشاف مساحات جديدة للتتبّع	معالجة الأحداث أو الردّ عليها بشكل دوري أو من خلال عامل تشغيل استرجاع الأحداث الفائتة من اشتراك (بسبب انقطاع الخدمة أو اشتراك غير نشط)
واجهة برمجة التطبيقات	واجهة برمجة التطبيقات لفعاليات 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 واجهة برمجة التطبيقات Google Workspace Events API subscriptions.create() لاشتراك في المساحة لجميع أنواع أحداث الاشتراكات. بعد إنشاء الاشتراك، يمكن أن يبدأ تطبيق Chat فيتلقّي أحداث الاشتراكات.

.

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

للتعرّف على كيفية إنشاء الاشتراكات باستخدام "واجهة برمجة تطبيقات أحداث Google Workspace"، راجِع مستندات "واجهة برمجة تطبيقات أحداث 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"، لن يتلقّى الاشتراك أحداث العضوية هذه. للتعرّف على آلية عمل العضويات في "مجموعة Google"، يُرجى الاطّلاع على القسم إضافة "مجموعة Google" إلى مساحة.

مواضيع ذات صلة

• نظرة عامة على واجهة برمجة تطبيقات أحداث Google Workspace
• إنشاء اشتراك
• الحصول على تفاصيل عن حدث في مساحة Google Chat
• عرض الأحداث من مساحة على Google Chat
• للحصول على أمثلة عن كيفية استخدام الأحداث، يمكنك الاطّلاع على البرنامج التعليمي الإجابة عن الأسئلة استنادًا إلى محادثات Chat باستخدام تطبيق Gemini Chat المستنِد إلى الذكاء الاصطناعي أو ميزة المساعدة في تعزيز الشمولية في تطبيق Chat المخصّص لإدارة المشاكل في الدليل التعليمي إنشاء تطبيقات لخدمة Google Chat باستخدام Gemini.