توضّح هذه الصفحة أحداث Chat التي يمكن لتطبيق Chat الاشتراك فيها باستخدام واجهة برمجة التطبيقات Google Workspace Events API. بعد تحديد أنواع الأحداث التي تحتاجها، أنشئ اشتراكًا لبدء تلقّي الأحداث من Chat.
بالإضافة إلى الاشتراك في الأحداث، يمكنك أيضًا الاستعلام عن الأحداث من خلال طلب Google Chat API. يتيح لك طلب Chat API استرداد الأحداث بشكل دوري أو الاطّلاع على الأحداث التي قد تكون فاتتك من اشتراك بسبب انقطاع الخدمة. للتعرّف على الطرق التي يمكنك من خلالها تلقّي أحداث Chat والردّ عليها، يُرجى الاطّلاع على العمل مع الأحداث من Chat في مستندات Chat.
أحداث Chat المتوافقة
تتيح لك اشتراكات Google Workspace تلقّي أحداث حول الأنواع التالية من التغييرات في Chat:
- الرسائل الجديدة أو المعدَّلة أو المحذوفة في المساحة
- التفاعلات الجديدة أو التي تمت إزالتها من رسالة
- الأعضاء الجدد أو المعدَّلون أو الذين تمت إزالتهم في المساحة
- التغييرات التي تطرأ على المساحة التي اشتركت فيها، مثل تعديل اسم المساحة أو وصفها
- التغييرات في مدى توفّر المستخدم
- التغييرات في spaceReadState أو threadReadState للمستخدم
الموارد التي يمكنك مراقبتها بحثًا عن الأحداث
لتلقّي الأحداث، عليك تحديد مورد Chat لمراقبته، ويُعرف باسم المورد المستهدَف للاشتراك.
تتيح واجهة Google Workspace Events API استخدام الموارد المستهدَفة التالية في Chat:
| المورد المستهدف | التنسيق | القيود |
|---|---|---|
| مسافة |
حيث يمثّل SPACE المعرّف في
اسم المورد لمورد |
يجب أن يكون مستخدم Chat أو تطبيق Chat الذي يفوّض الاشتراك عضوًا في المساحة من خلال حسابه على Google Workspace أو حسابه على Google. يتيح: |
| جميع المساحات لمستخدم معيّن |
|
لا يتلقّى الاشتراك سوى الأحداث الخاصة بالمساحات التي يكون فيها المستخدم عضوًا من خلال حسابه على Google Workspace أو حسابه على Google. تتيح هذه الطريقة مصادقة المستخدم فقط. |
| المستخدم |
حيث يمثّل USER المعرّف في
اسم المورد لمورد |
لا يتلقّى الاشتراك سوى الأحداث المتعلّقة بالمستخدم الذي سمح بالاشتراك. لا يمكن لمستخدم تفويض اشتراك نيابةً عن مستخدمين آخرين. تتيح هذه الطريقة مصادقة المستخدم فقط. |
| العميل |
حيث يمثّل CUSTOMER رقم تعريف العميل. يمكنك أيضًا استخدام العنوان البديل |
يتلقّى الاشتراك أحداثًا لجميع المساحات والمستخدمين الذين يديرهم نطاق العميل. يتيح فقط مصادقة التطبيق بموافقة المشرف. |
أنواع الأحداث لإنشاء الاشتراكات
عند إنشاء اشتراك، استخدِم الحقل
eventTypes[]
لتحديد أنواع الأحداث التي تريد تلقّيها. يتم تنسيق أنواع الأحداث وفقًا لمواصفات CloudEvents، مثل google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.
على سبيل المثال، لتلقّي أحداث حول انضمام المستخدمين إلى مساحة Chat، حدِّد المساحة كمورد مستهدَف ونوع الحدث على أنّه google.workspace.chat.membership.v1.created. لتلقّي أحداث حول انضمام مستخدم معيّن إلى أي مساحة، حدِّد المستخدم كمورد مستهدَف ونوع الحدث على أنّه google.workspace.chat.membership.v1.created. لمزيد من المعلومات حول آلية عمل الأحداث، يُرجى الاطّلاع على بنية أحداث Google Workspace.
يعرض الجدول التالي أنواع الأحداث المتوافقة مع الاشتراكات في المساحات والاشتراكات في المستخدمين. للتعرّف على الاستثناءات المتعلّقة بما يؤدي إلى بدء حدث، يُرجى الاطّلاع على القيود.
| نوع الحدث | التنسيق | بيانات الموارد | ||
|---|---|---|---|---|
| الاشتراكات في المساحات | ||||
| يتم نشر رسالة. |
|
|
||
| تعديل رسالة |
|
|
||
| تم حذف رسالة. |
|
|
||
| يتم إنشاء تفاعل. |
|
|
||
| تم حذف تفاعل. |
|
|
||
| تمت إضافة عضو إلى المساحة. |
|
|
||
| تم تعديل عضو في المساحة. |
|
|
||
| تتم إزالة عضو من المساحة. |
|
|
||
| تم تعديل المساحة. |
|
|
||
| تم حذف المساحة. |
|
|
||
| الاشتراكات للمستخدمين | ||||
| يصبح المستخدم عضوًا في مساحة.
لا تؤدي جميع الأعضاء الجدد إلى تشغيل الأحداث. لمعرفة التفاصيل، يُرجى الاطّلاع على القيود |
|
|
||
| يتم تعديل عضوية المستخدم في مساحة. |
|
|
||
| تتم إزالة المستخدم كعضو مباشر في مساحة. |
|
|
||
| يتم تعديل حالة قراءة مساحة المستخدم. |
|
|
||
| يتم تعديل حالة قراءة سلسلة المحادثات للمستخدم. |
|
|
||
| الاشتراكات للعملاء | ||||
| يحدث حدث لأي مساحة أو رسالة أو تفاعل أو عضوية أو حالة قراءة للمستخدم داخل مؤسستك على 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/يستبعد بيانات الموارد:
{
"message":
{
"name": "spaces/ |
| يصبح المستخدم مدير مساحة. |
|
يتضمّن بيانات الموارد:
{
"membership":
{
"name": "spaces/يستبعد بيانات الموارد:
{
"membership":
{
"name": "spaces/ |
| يعدّل مستخدم وصف المساحة إلى "فريق المبيعات في Cymbal Labs". | google.workspace.chat.space.v1.updated |
يتضمّن بيانات الموارد:
{
"space":
{
"name": "spaces/يستبعد بيانات الموارد:
{
"space":
{
"name": "spaces/ |
| تمت إضافة مستخدمَين في Chat إلى المساحة في الوقت نفسه. | google.workspace.chat.membership.v1.batchCreated |
يتضمّن بيانات الموارد:
{
"memberships": [
{
"membership": {
"name": "spaces/يستبعد بيانات الموارد:
{
"memberships": [
{
"membership": {
"name": "spaces/ |
| يتفاعل مستخدم مع رسالة باستخدام الإيموجي 😊. | google.workspace.chat.reaction.v1.created |
يتضمّن بيانات الموارد:
{
"reaction":
{
"name": "spaces/يستبعد بيانات الموارد:
{
"reaction":
{
"name": "spaces/ |
| يتفاعل المستخدمون مع رسالة باستخدام الإيموجي 😊 والإيموجي 😸. | google.workspace.chat.reaction.v1.batchCreated |
يتضمّن بيانات الموارد:
{
"reactions": [
{
"reaction": {
"name": "spaces/يستبعد بيانات الموارد:
{
"reactions": [
{
"reaction": {
"name": "spaces/ |
| يزور مستخدم مساحة غير مقروءة، ما يؤدي إلى تعديل حالة قراءة المساحة. | google.workspace.chat.spaceReadState.v1.updated |
يتضمّن بيانات الموارد:
{
"spaceReadState": {
"name": "users/يستبعد بيانات الموارد:
{
"spaceReadState": {
"name": "users/ |
| يقرأ مستخدم رسالة في سلسلة محادثات، ما يؤدي إلى تعديل حالة قراءة سلسلة المحادثات. | google.workspace.chat.threadReadState.v1.updated |
يتضمّن بيانات الموارد:
{
"threadReadState": {
"name": "users/يستبعد بيانات الموارد:
{
"threadReadState": {
"name": "users/ |
| يصبح المستخدم متاحًا في Chat. | google.workspace.chat.availability.v1.updated |
يتضمّن بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "ACTIVE"
}
}
يستبعد بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
| يصبح المستخدم غير نشط في Chat. | google.workspace.chat.availability.v1.updated |
يتضمّن بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "IDLE",
}
}
يستبعد بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
يضبط المستخدم حالة توفّره على "Away" في Chat. |
google.workspace.chat.availability.v1.updated |
يتضمّن بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "AWAY",
}
}
يستبعد بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
يضبط المستخدم حالة توفّره على "Do not disturb" في Chat. |
google.workspace.chat.availability.v1.updated |
يتضمّن بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "DO_NOT_DISTURB",
"doNotDisturbMetadata": {
"expirationTime": "2026-03-24T18:36:31.337Z"
}
}
}
يستبعد بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
| يضبط مستخدم حالة مخصّصة على Chat. | google.workspace.chat.availability.v1.updated |
يتضمّن بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
"state": "ACTIVE",
"customStatus": {
"text": "Be right back",
"emoji": {
"unicode": "👟"
},
"expireTime": "2026-03-24T18:38:05.583655Z"
}
}
}
يستبعد بيانات الموارد:
{
"availability":
{
"name": "users/USER_ID/availability",
}
}
|
القيود وسلوكيات التسليم
القيود العامة
- لتلقّي أحداث العضوية، يجب أن يكون المستخدم أو تطبيق 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}
المواضيع ذات الصلة
- بنية أحداث Google Workspace
- اختيار نطاقات OAuth
- إنشاء اشتراك لتلقّي أحداث Chat