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

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

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

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

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

الاستعلام عن أحداث العضوية الأخيرة

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

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

في الشكل 3، يستدعي تطبيق Chat طريقة spaces.spaceEvents.list() في Chat API بعد حدوث جميع أنشطة العضوية، ويفلتر طلب البحث عن أحداث العضوية الجديدة والمعدَّلة والمحذوفة. تعرض واجهة 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}