استخدام الأحداث من 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 ( معاينة المطور) المساحات فقط
الأحداث المتوافقة
  • الرسائل
  • العضويات
  • التفاعلات
  • مسافة

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

القيود وسلوكيات التسليم

القيود العامة

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

اشتراكات المستخدم

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

اشتراكات العملاء ( معاينة المطوّرين)

تنطبق القيود التالية على اشتراكات العملاء:

  • يجب أن يكون لدى مؤسسة Google Workspace ترخيص واحد على الأقل من حزمة Enterprise. يُرجى العِلم أنّ هذا الشرط لن يتم تطبيقه بشكل صارم خلال مرحلة "برنامج معاينة المطوّرين"، ولكن سيتم تطبيقه في المستقبل (وسيتم الإعلان عنه بشكل منفصل).
  • يمكن لتطبيق Chat إنشاء اشتراك واحد فقط للعملاء لمؤسسة معيّنة على Google Workspace. يمكن أن يكون لمؤسسة Google Workspace ما يصل إلى خمس اشتراكات عملاء إجمالاً (تم إنشاؤها بواسطة تطبيقات Chat مختلفة).

بالنسبة إلى اشتراكات العملاء، يخضع عرض الأحداث للقواعد العامة التالية:

  • أحداث المساحة: يتم تسليمها فقط إذا وقع الحدث في مساحة تديرها مؤسسة Google Workspace.
  • أحداث المستخدم: يتم تسليمها فقط إذا حدث الحدث لمستخدم ينتمي إلى مؤسستك على Google Workspace.

الاستثناء الوحيد لهذه القواعد هو أحداث العضوية. يمكن أن يتلقّى اشتراكك أحداث العضوية من كلّ من المساحات التي تديرها مؤسستك والمساحات التي تديرها مؤسسات خارجية، ولكن تعتمد طريقة تسليمها على المؤسسة التي تدير المساحة:

المساحات التي تديرها مؤسستك على Google Workspace

في حال حدوث تغيير في العضوية في مساحة تديرها مؤسسة Google Workspace، يتم إرسال هذا التغيير كـ حدث في المساحة.

يستخدم اسم المرجع لحدث في مساحة التنسيق التالي:

spaces/{spaceId}/spaceEvents/{spaceEventId}

المساحات التي تديرها مؤسسات خارجية

إذا تغيّرت عضوية مستخدم تديره مؤسستك على Google Workspace في مساحة تديرها مؤسسة خارجية (مثل مساحة خارجية تحمل اسمًا أو رسالة مباشرة أنشأها مستخدم خارجي)، سيتلقّى اشتراكك هذا الحدث كحدث مستخدم.

يستخدم اسم مورد حدث المستخدم التنسيق التالي:

users/{userId}/userEvents/{userEventId}