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

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

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

أحداث Chat المتاحة

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

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

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

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

تتوافق واجهة برمجة التطبيقات Google Workspace Events API مع الموارد المستهدَفة التالية: بالنسبة إلى Chat:

المورد المستهدف التنسيق القيود
مسافة

//chat.googleapis.com/spaces/SPACE

حيث SPACE هو المعرّف في اسم المورد الخاص بمورد space في Chat API. يمكنك الحصول على المعرّف من عنوان URL للمساحة أو باستخدام spaces.list().

 على مستخدم Chat الذي يسمح بالاشتراك: أن تكون عضوًا في مساحة العمل من خلال Google Workspace أو Google الحساب.
جميع المساحات لمستخدم

//chat.googleapis.com/spaces/-

 لا يتلقّى الاشتراك إلا أحداث المساحات التي يكون المستخدم فيها فرد من خلال حسابه على Google Workspace أو Google.
مستخدم

//cloudidentity.googleapis.com/users/USER

حيث USER هو المعرّف في اسم المورد الخاص بمورد user في Chat API. للحصول على التفاصيل، يمكنك مراجعة التحديد والتحديد مستخدمو Google Chat

لا يتلقّى الاشتراك إلا الأحداث المتعلقة بالمستخدم الذي قد صادقوا على الاشتراك. لا يمكن للمستخدم تفويض اشتراك في بالنيابة عن المستخدمين الآخرين.

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

عند إنشاء اشتراك، يمكنك استخدام 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.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

بيانات الحدث

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

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

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

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

يعرض الجدول التالي أمثلة على حمولات 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"، لتلقي أحداث العضوية هذه. لفهم آلية عمل اشتراكات "مجموعات Google"، يمكنك الاطّلاع على إضافة "مجموعة Google" إلى مساحة