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

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

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

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

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

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

الموارد التي يمكنك مراقبة الأحداث فيها

لتلقّي الأحداث، عليك تحديد مورد 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