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

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

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

الموارد المستهدَفة المتوافقة مع Chat

تتيح Google Workspace Events API الاشتراكات التالية:

  • المساحات، يتم تمثيلها كموارد space
  • المستخدمون، الذين يتم تمثيلهم كموارد في Cloud Identity API user

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

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

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

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

عند إنشاء اشتراك، يمكنك استخدام الحقل eventTypes[] لتحديد أنواع الأحداث التي تريد تلقّيها. يتم تنسيق أنواع الأحداث وفقًا لمواصفات CloudEvent، مثل 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 إلى مساحة.