الاشتراك في أحداث Google Chat

تصف هذه الصفحة فعاليات 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.

يعرض الجدول التالي أنواع الأحداث المتاحة لاشتراكات المساحات والاشتراكات المقدَّمة للمستخدمين. لمعرفة المزيد من المعلومات عن الاستثناءات حول عوامل تشغيل حدث، يُرجى الاطّلاع على القيود.

نوع الحدث التنسيق بيانات الموارد
الاشتراكات في المساحات  
يتم نشر رسالة.

google.workspace.chat.message.v1.created

space.message
تم تعديل رسالة.

google.workspace.chat.message.v1.updated

space.message
يتم حذف الرسالة.

google.workspace.chat.message.v1.deleted

space.message
يتم إنشاء تفاعل.

google.workspace.chat.reaction.v1.created

space.message.reaction
يتم حذف التفاعل.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
إضافة عضو إلى المساحة

google.workspace.chat.membership.v1.created

space.membership
يتم تعديل عضو في المساحة.

google.workspace.chat.membership.v1.updated

space.membership
تتم إزالة عضو من المساحة.

google.workspace.chat.membership.v1.deleted

space.membership
تم تعديل المساحة.

google.workspace.chat.space.v1.updated

space
تم حذف المساحة.

google.workspace.chat.space.v1.deleted

space
الاشتراكات للمستخدمين  
يصبح المستخدم عضوًا في مساحة.

لا يقوم جميع الأعضاء الجدد بتشغيل الأحداث. لمعرفة التفاصيل، يُرجى الاطّلاع على القيود.

google.workspace.chat.membership.v1.created

space.membership
يتم تعديل عضوية المستخدم في مساحة.

google.workspace.chat.membership.v1.updated

space.membership
تتم إزالة المستخدم كعضو مباشر في المساحة.

google.workspace.chat.membership.v1.deleted

space.membership

أنواع الأحداث المجمّعة (الناتج فقط)

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

على سبيل المثال، إذا أضاف مستخدم 20 مستخدمًا إلى مساحة في الوقت نفسه، قد يتلقّى تطبيق Chat حدثًا مجمّعًا (google.workspace.chat.membership.v1.batchCreated). تحتوي حمولة الحدث على قائمة بجميع موارد Membership الجديدة التي تم إنشاؤها عندما أضاف المستخدم الأعضاء إلى المساحة.

ستتلقّى حدثًا مجمّعًا لأي نوع حدث تشترك فيه، لذلك لن تحتاج إلى تحديد أحداث مجمَّعة عند إنشاء اشتراك. على سبيل المثال، إذا اشتركت في التفاعلات الجديدة (google.workspace.chat.reaction.v1.created)، يتم ضبط تطبيقك في Chat تلقائيًا على تلقّي أحداث التفاعلات المجمّعة (google.workspace.chat.reaction.v1.batchCreated).

يعرض الجدول التالي الأحداث المجمّعة المحتملة للاشتراك:

نوع الحدث المجمَّع التنسيق
يتم نشر رسائل متعددة.

google.workspace.chat.message.v1.batchCreated
تم تعديل رسائل متعددة.

google.workspace.chat.message.v1.batchUpdated
يتم حذف عدة رسائل.

google.workspace.chat.message.v1.batchDeleted
يتم إنشاء تفاعلات متعدّدة.

google.workspace.chat.reaction.v1.batchCreated
يتم حذف التفاعلات المتعددة.

google.workspace.chat.reaction.v1.batchDeleted
تتم إضافة عدة أعضاء إلى المساحة التي تم الاشتراك فيها أو إضافة المستخدم المشترك إلى مساحات متعددة.

google.workspace.chat.membership.v1.batchCreated
يتم تعديل عدة عضويات في المساحة التي اشتركت فيها أو للمستخدم المشترك.

google.workspace.chat.membership.v1.batchUpdated
تتم إزالة عدة أعضاء من المساحة التي اشتركت فيها أو تمت إزالة المستخدم المشترك من مساحات متعددة.

google.workspace.chat.membership.v1.batchDeleted
تحتوي المساحة على تعديلات متعددة.

google.workspace.chat.space.v1.batchUpdated

بيانات الحدث

يصف هذا القسم بيانات الأحداث وأمثلة على الحمولات للأحداث في Chat.

عندما يتلقّى اشتراكك في Google Workspace حدثًا من Chat، يحتوي الحقل data على حمولة الحدث. تحتوي هذه الحمولة على معلومات حول مورد Google Workspace الذي تم تغييره. مثلاً، إذا كنت قد اشتركت في أحداث عضوية في مساحة، تحتوي حمولة هذه الأحداث على معلومات حول مورد spaces.membership الذي تم تغييره.

بيانات الموارد في حمولة الحدث

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

يعرض الجدول التالي أمثلة على حمولات JSON الأساسية للاشتراك في مساحة Chat spaces/AAAABBBBBB. بالنسبة إلى كلّ حدث يتلقّاه الاشتراك، تظهر الحمولة في الحقل data الخاص بالحدث:

مثال نوع الحدث حمولة JSON

ينشر أحد المستخدمين رسالة في المساحة بعنوان "مرحبًا بالعالم".

google.workspace.chat.message.v1.created

يتضمّن بيانات الموارد
{
    "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"
    }
}
يصبح المستخدم مدير المساحة.

google.workspace.chat.membership.v1.updated

يتضمّن بيانات الموارد
{
    "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 إلى مساحة.