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

تصف هذه الصفحة أحداث Chat التي يمكن لتطبيق Chat الاشتراك فيها باستخدام Google Workspace Events API. بعد تحديد أنواع الأحداث التي تحتاج إليها، أنشئ اشتراكًا لبدء تلقّي الأحداث من Chat.

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

أحداث Chat المتوافقة

تتيح لك اشتراكات Google Workspace تلقّي أحداث حول الأنواع التالية من التغييرات في Chat:

• الرسائل الجديدة أو المعدَّلة أو المحذوفة في المساحة.
• التفاعلات الجديدة أو التي تمت إزالتها reactions من رسالة
• الأعضاء الجدد أو الذين تمت إزالتهم أو تعديل معلوماتهم members في المساحة
• التغييرات في المساحة التي اشتركت فيها، مثل اسم المساحة أو وصفها المعدَّلَين

المراجع التي يمكنك مراقبتها بحثًا عن الأحداث

لتلقّي الأحداث، عليك تحديد مرجع Chat لمراقبته، ويُعرف باسم المرجع المستهدف للاشتراك.

تتيح Google Workspace Events API المراجع المستهدَفة التالية لـ Chat:

أنواع الأحداث لإنشاء الاشتراكات

عند إنشاء اشتراك، استخدِم الـ 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 للحدث:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}
      

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
      

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
      

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
      

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
      

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
      

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
      

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
      

• بالنسبة إلى الاشتراكات في المستخدمين، لا يتم تشغيل الأحداث الخاصة بالأعضاء الجدد في الرسائل المباشرة أو المحادثات الجماعية غير المُسمّاة (google.workspace.chat.membership.v1.created)، إلا بعد نشر الرسالة الأولى.
• لتلقّي أحداث العضوية، يجب أن يكون المستخدم أو تطبيق Chat عضوًا مباشرًا في المساحة. إذا تمت إضافة المستخدم أو تعديل معلوماته أو إزالته بشكل غير مباشر من مساحة من خلال "مجموعة Google"، لن يتلقّى الاشتراك أحداث العضوية هذه. للتعرّف على طريقة عمل عضويات "مجموعة Google"، اطّلِع على مقالة إضافة "مجموعة Google" إلى مساحة.

مواضيع ذات صلة

• بنية أحداث Google Workspace
• اختيار نطاقات OAuth
• إنشاء اشتراك لتلقّي أحداث Chat