توضّح هذه الصفحة كيف يمكن لتطبيقات 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 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
في تلقّي أحداث مرتبطة بالعضويات.
في الشكل 2، يحتوي تطبيق Chat على اشتراك نشِط في المساحة، لذلك يتلقّى التطبيق حدثًا كلما تغيّر الاشتراك في المساحة. يمكن لتطبيق Chat بعد ذلك معالجة أي من الأنشطة أو الرد عليها في الوقت الفعلي، مثل نشر رسالة ترحيب خاصة للعضو الذي انضم إلى المساحة.
للتعرُّف على معلومات عن إنشاء الاشتراكات باستخدام Google Workspace Events API، يمكنك الاطّلاع على مستندات Google Workspace Events API.
طلب بحث عن أحداث العضوية الأخيرة
بدلاً من تلقّي أحداث الاشتراك عند حدوثها، يمكن لتطبيق 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 Events API
- إنشاء اشتراك
- الحصول على تفاصيل عن حدث في "مساحة Google Chat"
- سرد الأحداث من مساحة Google Chat
- للاطّلاع على أمثلة حول كيفية استخدام الأحداث، اطّلِع على الدليل التوجيهي الإجابة عن أسئلة تستند إلى محادثات Chat باستخدام تطبيق Gemini AI Chat أو ميزة المساعدة المتعلقة بالشمولية في تطبيق Chat لإدارة المشاكل. ضمن الدرس التطبيقي حول الترميز إنشاء تطبيقات لـ Google Chat باستخدام Gemini