تصف هذه الصفحة أحداث Google Chat التي يمكن لتطبيق Google Chat الاشتراك فيها باستخدام Google Workspace Events API. بعد تحديد أنواع الأحداث التي تحتاج إليها، يمكنك إنشاء اشتراك لبدء تلقّي الأحداث من Google Chat.
بالإضافة إلى الاشتراك في الأحداث، يمكنك أيضًا البحث عن الأحداث من خلال طلب بيانات Chat API. يتيح لك الاتصال بواجهة برمجة التطبيقات Chat API retrieving events على أساس دوري، أو متابعة events التي ربما فاتك الحصول عليها من اشتراك بسبب انقطاع الخدمة. للتعرّف على الطُرق التي يمكنك من خلالها تلقّي أحداث Chat والردّ عليها، اطّلِع على العمل مع الأحداث من Google Chat في مستندات Chat.
أحداث Chat المتوافقة
تتيح لك اشتراكات Google Workspace تلقّي أحداث حول الأنواع التالية من التغييرات في Chat:
- الرسائل الجديدة أو المعدَّلة أو المحذوفة في المساحة
- تفاعلات جديدة أو تمت إزالتها في رسالة
- الأعضاء الجدد أو المعدَّلين أو الذين تمّت إزالتهم في المساحة
- التغييرات في المساحة التي اشتركت فيها، مثل اسم المساحة أو وصفها المعدَّلَين
الموارد التي يمكنك رصدها بحثًا عن الأحداث
لتلقّي الأحداث، عليك تحديد مورد Chat للتتبّع، وهو ما يُعرف باسم المورد المستهدَف للاشتراك.
تتوافق واجهة برمجة التطبيقات Google Workspace Events API مع الموارد المستهدَفة التالية لتطبيق Chat:
| المورد المستهدَف | التنسيق | القيود |
|---|---|---|
| مسافة |
حيث يكون SPACE هو المعرّف في
اسم المورد لمورد Chat API |
يجب أن يكون مستخدم Chat الذي يفوّض الاشتراك عضوًا في المساحة من خلال حسابه على Google Workspace أو Google. |
| جميع المساحات الخاصة بمستخدم |
|
لا يتلقّى الاشتراك سوى الأحداث للمساحات التي يكون فيها المستخدم عضوًا من خلال حسابه على Google Workspace أو Google. |
| المستخدم |
حيث يكون USER هو المعرّف في
اسم المورد لمورد Chat API |
لا يتلقّى الاشتراك سوى الأحداث المتعلّقة بالمستخدم الذي أذن بالاشتراك. لا يمكن للمستخدم تفويض اشتراك نيابةً عن مستخدمين آخرين. |
أنواع الأحداث لإنشاء الاشتراكات
عند إنشاء اشتراك، يمكنك استخدام الحقل
eventTypes[]
لتحديد أنواع الأحداث التي تريد تلقّيها. يتم تنسيق أنواع الأحداث
وفقًا لمواصفات CloudEvents، مثل
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"، لن يتلقّى الاشتراك أحداث العضوية هذه. للتعرّف على آلية عمل العضويات في "مجموعة Google"، يُرجى الاطّلاع على القسم إضافة "مجموعة Google" إلى مساحة.
مواضيع ذات صلة
- بنية أحداث Google Workspace
- اختيار نطاقات OAuth
- إنشاء اشتراك لتلقّي أحداث Chat