استخدام الأحداث من 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 حدثًا يحتوي على بيانات عن الرسالة الجديدة message.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

للتعرّف على كيفية إنشاء الاشتراكات باستخدام Google Workspace Events API، يُرجى مراجعة مستندات Google Workspace Events API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

المساحات التي تديرها مؤسسة Google Workspace

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

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

spaces/{spaceId}/spaceEvents/{spaceEventId}

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

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

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

users/{userId}/userEvents/{userEventId}