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

تطبيق في 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.

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