استخدام الأحداث من 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.

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

الاشتراك في الأحداث طلب البحث عن الأحداث
حالات الاستخدام
  • معالجة الأحداث أو الرد عليها في الوقت الفعلي.
  • مراقبة سلوك المستخدمين نشاط العضوية واكتشاف مساحات جديدة الشاشة.
  • معالجة الأحداث أو الاستجابة لها بشكل دوري أو من خلال عامل تشغيل.
  • يمكنك جلب الأحداث الفائتة من أحد الاشتراكات (بسبب انقطاع أو اشتراك غير نشط).
واجهة برمجة التطبيقات واجهة برمجة التطبيقات لفعاليات 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
الشكل 2. تطبيق Chat أحداث العضوية من خلال اشتراك يستخدم واجهة برمجة التطبيقات لفعاليات Google Workspace.

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

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

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

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

تطبيق Chat الذي يبحث عن الأحداث باستخدام واجهة برمجة التطبيقات Chat
الشكل 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" إلى مساحة