تصف هذه الصفحة فعاليات Google Chat التي يمكن لتطبيق Google Chat الاشتراك فيها باستخدام Google Workspace Events API. بعد أن تقرر أنواع الأحداث التي تحتاج إليها، يمكنك إنشاء اشتراك لبدء تلقّي الأحداث من Google Chat.
إضافةً إلى الاشتراك في الفعاليات، يمكنك أيضًا طلب البحث عن الفعاليات من خلال استدعاء Chat API. يتيح لك استدعاء واجهة برمجة تطبيقات Chat استرداد الأحداث بشكل دوري أو متابعة الأحداث التي قد تكون فاتتك بسبب أحد الاشتراكات بسبب انقطاع الخدمة. للتعرّف على طرق تلقّي أحداث Chat والردّ عليها، يمكنك الاطّلاع على التعامل مع الأحداث من Google Chat في مستندات Chat.
المراجع المتاحة لاستهداف Chat
تتيح واجهة برمجة التطبيقات Google Workspace Events API الاشتراكات للأغراض التالية:
- المساحات، يتم تمثيلها كـ
space
مورد - المستخدمون، الذين يتم تمثيلهم كموارد
user
في Cloud Identity API
أحداث Chat المتاحة
تتيح لك اشتراكات Google Workspace تلقّي أحداث عن أنواع التغييرات التالية في Chat:
- الرسائل الجديدة أو المعدّلة أو المحذوفة في المساحة
- تفاعلات جديدة أو تمت إزالتها تجاه رسالة معيّنة
- الأعضاء الجدد أو المعدّلون أو الذين تمت إزالتهم في المساحة
- تغييرات على المساحة التي اشتركت فيها، مثل تعديل اسم المساحة أو وصفها
أنواع الأحداث لإنشاء الاشتراكات
عند إنشاء اشتراك، يمكنك استخدام الحقل
eventTypes[]
لتحديد أنواع الأحداث التي تريد تلقّيها. يتم تنسيق أنواع الأحداث
وفقًا لمواصفات Cloud Events، مثل
google.workspace.APPLICATION.RESOURCE.VERSION.ACTION
.
على سبيل المثال، لتلقّي أحداث حول انضمام المستخدمين إلى مساحة Chat، عليك تحديد المساحة كمورد مستهدف، ونوع الحدث على النحو التالي
google.workspace.chat.membership.v1.created
. لتلقّي أحداث حول انضمام مستخدم معيَّن إلى أي مساحة، عليك تحديد هذا المستخدم باعتباره المورد المستهدف، ونوع الحدث على أنّه google.workspace.chat.membership.v1.created
. لمزيد من المعلومات عن آلية عمل الأحداث، يمكنك الاطّلاع على بنية أحداث Google Workspace.
يعرض الجدول التالي أنواع الأحداث المتاحة لاشتراكات المساحات والاشتراكات المقدَّمة للمستخدمين. لمعرفة المزيد من المعلومات عن الاستثناءات حول عوامل تشغيل حدث، يُرجى الاطّلاع على القيود.
نوع الحدث | التنسيق | بيانات الموارد | ||
---|---|---|---|---|
الاشتراكات في المساحات | ||||
يتم نشر رسالة. |
|
|
||
تم تعديل رسالة. |
|
|
||
يتم حذف الرسالة. |
|
|
||
يتم إنشاء تفاعل. |
|
|
||
يتم حذف التفاعل. |
|
|
||
إضافة عضو إلى المساحة |
|
|
||
يتم تعديل عضو في المساحة. |
|
|
||
تتم إزالة عضو من المساحة. |
|
|
||
تم تعديل المساحة. |
|
|
||
تم حذف المساحة. |
|
|
||
الاشتراكات للمستخدمين | ||||
يصبح المستخدم عضوًا في مساحة.
لا يقوم جميع الأعضاء الجدد بتشغيل الأحداث. لمعرفة التفاصيل، يُرجى الاطّلاع على القيود. |
|
|
||
يتم تعديل عضوية المستخدم في مساحة. |
|
|
||
تتم إزالة المستخدم كعضو مباشر في المساحة. |
|
|
أنواع الأحداث المجمّعة (الناتج فقط)
بالإضافة إلى تلقّي أنواع الأحداث التي تشترك فيها، قد يتلقّى تطبيق Chat أيضًا أحداثًا مجمَّعة. الحدث المجمّع هو حدث يمثّل العديد من الأحداث من النوع نفسه التي تقع خلال فترة زمنية قصيرة. تحتوي حمولة الحدث المجمّع على قائمة بجميع الموارد التي تم تغييرها.
على سبيل المثال، إذا أضاف مستخدم 20 مستخدمًا إلى مساحة في الوقت نفسه، قد يتلقّى تطبيق Chat حدثًا مجمّعًا (google.workspace.chat.membership.v1.batchCreated
). تحتوي حمولة الحدث على قائمة بجميع موارد Membership
الجديدة التي تم إنشاؤها عندما أضاف المستخدم الأعضاء إلى المساحة.
ستتلقّى حدثًا مجمّعًا لأي نوع حدث تشترك فيه، لذلك لن تحتاج إلى تحديد أحداث مجمَّعة عند إنشاء اشتراك. على سبيل المثال، إذا اشتركت في التفاعلات الجديدة (google.workspace.chat.reaction.v1.created
)، يتم ضبط
تطبيقك في Chat تلقائيًا على تلقّي أحداث
التفاعلات المجمّعة (google.workspace.chat.reaction.v1.batchCreated
).
يعرض الجدول التالي الأحداث المجمّعة المحتملة للاشتراك:
نوع الحدث المجمَّع | التنسيق |
---|---|
يتم نشر رسائل متعددة. |
|
تم تعديل رسائل متعددة. |
|
يتم حذف عدة رسائل. |
|
يتم إنشاء تفاعلات متعدّدة. |
|
يتم حذف التفاعلات المتعددة. |
|
تتم إضافة عدة أعضاء إلى المساحة التي تم الاشتراك فيها أو إضافة المستخدم المشترك إلى مساحات متعددة. |
|
يتم تعديل عدة عضويات في المساحة التي اشتركت فيها أو للمستخدم المشترك. |
|
تتم إزالة عدة أعضاء من المساحة التي اشتركت فيها أو تمت إزالة المستخدم المشترك من مساحات متعددة. |
|
تحتوي المساحة على تعديلات متعددة. |
|
بيانات الحدث
يصف هذا القسم بيانات الأحداث وأمثلة على الحمولات للأحداث في Chat.
عندما يتلقّى اشتراكك في Google Workspace حدثًا من
Chat، يحتوي الحقل
data
على حمولة الحدث. تحتوي هذه الحمولة على معلومات حول
مورد Google Workspace الذي تم تغييره. مثلاً، إذا كنت قد اشتركت في أحداث عضوية في مساحة، تحتوي حمولة هذه الأحداث على معلومات حول مورد spaces.membership
الذي تم تغييره.
بيانات الموارد في حمولة الحدث
عند إنشاء اشتراك، يمكنك تحديد ما إذا كنت تريد تضمين تفاصيل حول المورد في البيانات الأساسية، أو اسم المورد فقط. على سبيل المثال، إذا أردت تلقّي أحداث حول الأعضاء في مساحة Chat، يمكنك تحديد حقول مورد العضوية التي تريد تلقّيها في حمولة الحدث.
يعرض الجدول التالي أمثلة على حمولات JSON الأساسية للاشتراك في
مساحة Chat spaces/AAAABBBBBB
. بالنسبة إلى كلّ حدث يتلقّاه الاشتراك، تظهر الحمولة في الحقل data
الخاص بالحدث:
مثال | نوع الحدث | حمولة JSON |
---|---|---|
ينشر أحد المستخدمين رسالة في المساحة بعنوان "مرحبًا بالعالم". |
|
يتضمّن بيانات الموارد
{ "message": { "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD", "sender": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "2023-09-07T21:37:36.260127Z", "text": "Hello world", "thread": { "name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE" }, "space": { "name": "spaces/AAAABBBBBB" }, "argumentText": "Hello world" } } يتم استبعاد بيانات الموارد
{ "message": { "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD" } } |
يصبح المستخدم مدير المساحة. |
|
يتضمّن بيانات الموارد
{ "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321", "state": "JOINED", "member": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MANAGER" } } يتم استبعاد بيانات الموارد
{ "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321" } } |
يعدِّل أحد المستخدمين وصف المساحة ليصبح "فريق المبيعات في Cymbal Labs". | google.workspace.chat.space.v1.updated |
يتضمّن بيانات الموارد
{ "space": { "name": "spaces/AAAABBBBBB", "displayName": "Cymbal Sales", "spaceThreadingState": "THREADED_MESSAGES", "spaceType": "SPACE", "spaceDetails": { "description": "Sales team for Cymbal Labs." }, "spaceHistoryState": "HISTORY_ON" } } يتم استبعاد بيانات الموارد
{ "space": { "name": "spaces/AAAABBBBBB" } } |
تمت إضافة مستخدمَين في Chat إلى المساحة في الوقت نفسه. | google.workspace.chat.membership.v1.batchCreated |
يتضمّن بيانات الموارد
{ "memberships": [ { "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321", "state": "JOINED", "member": { "name": "users/1234567890987654321", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MEMBER" } }, { "membership": { "name": "spaces/AAAABBBBBB/members/987654321234567890", "state": "JOINED", "member": { "name": "users/987654321234567890", "type": "HUMAN" }, "createTime": "1970-01-01T00:00:00Z", "role": "ROLE_MEMBER" } } ] } يتم استبعاد بيانات الموارد
{ "memberships": [ { "membership": { "name": "spaces/AAAABBBBBB/members/1234567890987654321" } }, { "membership": { "name": "spaces/AAAABBBBBB/members/98765432123456789019" } } ] } |
يتفاعل مستخدم مع رسالة باستخدام الرمز التعبيري 😊. | google.workspace.chat.reaction.v1.created |
يتضمّن بيانات الموارد
{ "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222", "user": { "name": "users/1234567890987654321", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } } يفحص بيانات الموارد
{ "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222" } } |
يتفاعل المستخدمون مع الرسالة باستخدام الرموز التعبيرية 😊 و😸. | google.workspace.chat.reaction.v1.batchCreated |
يتضمّن بيانات الموارد
{ "reactions": [ { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222", "user": { "name": "users/1234567890987654321", "type": "HUMAN" }, "emoji": { "unicode": "😊" } } }, { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444", "user": { "name": "users/98765431234564321", "type": "HUMAN" }, "emoji": { "unicode": "😸" } } } ] } يفحص بيانات الموارد
{ "reactions": [ { "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222" }, "reaction": { "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444", } } ] } |
القيود
-
بالنسبة إلى اشتراكات المستخدمين، لا تبدأ الأحداث الخاصة بالأعضاء الجدد في الرسائل المباشرة أو المحادثات الجماعية بدون اسم (
google.workspace.chat.membership.v1.created
) إلا بعد نشر الرسالة الأولى. - لا تؤدي التغييرات في سجلّ المساحات إلى تشغيل أحداث المساحة المعدَّلة (نوع الحدث:
google.workspace.chat.spaces.v1.updated
). - لتلقّي أحداث العضوية، يجب أن يكون المستخدم عضوًا مباشرًا في المساحة. إذا تمت إضافة مستخدم إلى مساحة أو تعديله أو إزالته بشكل غير مباشر من خلال "مجموعة Google"، لا يتلقّى الاشتراك أحداث العضوية هذه. لفهم طريقة عمل اشتراكات "مجموعات Google"، يُرجى الاطّلاع على إضافة مجموعة Google إلى مساحة.
مواضيع ذات صلة
- بنية أحداث Google Workspace
- اختيار نطاقات OAuth
- يمكنك إنشاء اشتراك لتلقّي أحداث Chat