تصف هذه الصفحة أحداث Google Chat التي يمكن لتطبيق Google Chat الاشتراك فيها باستخدام Google Workspace Events API. بعد تحديد أنواع الأحداث التي تحتاج إليها، يمكنك إنشاء اشتراك لبدء تلقّي الأحداث من Google Chat.
بالإضافة إلى الاشتراك في الأحداث، يمكنك أيضًا طلب البحث عن الأحداث من خلال استدعاء Chat API. يتيح لك طلب البيانات من خلال Chat API استرداد الأحداث بشكل دوري أو متابعة الأحداث التي قد تكون فاتتك في الاشتراك بسبب انقطاع الخدمة. للتعرّف على طرق تلقّي أحداث Chat والردّ عليها، يمكنك الاطّلاع على المقالة التعامل مع الأحداث من Google Chat في مستندات Chat.
الموارد المستهدَفة المتوافقة مع Chat
تتيح Google Workspace Events API الاشتراكات التالية:
- المساحات، يتم تمثيلها كموارد
space - المستخدمون، الذين يتم تمثيلهم كموارد في Cloud Identity API
user
أحداث Chat المتوافقة
تتيح لك اشتراكات Google Workspace تلقّي أحداث حول أنواع التغييرات التالية في Chat:
- الرسائل الجديدة أو المعدّلة أو المحذوفة في المساحة.
- التفاعلات الجديدة أو التي تمت إزالتها مع رسالة
- الأعضاء الجدد أو المعدّلون أو الذين تمت إزالتهم في المساحة
- التغييرات على المساحة التي اشتركت فيها، مثل تعديل اسم المساحة أو وصفها
أنواع الأحداث لإنشاء الاشتراكات
عند إنشاء اشتراك، يمكنك استخدام الحقل
eventTypes[]
لتحديد أنواع الأحداث التي تريد تلقّيها. يتم تنسيق أنواع الأحداث
وفقًا لمواصفات CloudEvent، مثل
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