در رویدادهای چت Google مشترک شوید

این صفحه رویدادهای گوگل چت را که یک برنامه گوگل چت می‌تواند با استفاده از Google Workspace Events API در آنها مشترک شود، شرح می‌دهد. پس از اینکه تصمیم گرفتید به چه نوع رویدادهایی نیاز دارید، برای شروع دریافت رویدادها از گوگل چت، یک اشتراک ایجاد کنید .

علاوه بر اشتراک در رویدادها، می‌توانید با فراخوانی Chat API، رویدادها را جستجو کنید. فراخوانی Chat API به شما امکان می‌دهد رویدادها را به صورت دوره‌ای بازیابی کنید، یا رویدادهایی را که ممکن است به دلیل قطعی از اشتراک از دست داده باشید، دریافت کنید. برای کسب اطلاعات در مورد روش‌های دریافت و پاسخ به رویدادهای Chat، به بخش «کار با رویدادها از Google Chat» در مستندات Chat مراجعه کنید.

رویدادهای چت پشتیبانی شده

اشتراک‌های Google Workspace به شما امکان می‌دهند رویدادهای مربوط به انواع تغییرات زیر را در Chat دریافت کنید:

  • پیام‌های جدید، به‌روزرسانی‌شده یا حذف‌شده در این فضا.
  • واکنش‌های جدید یا حذف‌شده به یک پیام.
  • اعضای جدید، به‌روزرسانی‌شده یا حذف‌شده در این فضا.
  • تغییرات در فضایی که در آن مشترک شده‌اید، مانند به‌روزرسانی نام یا توضیحات فضا.

منابعی که می‌توانید برای رویدادها رصد کنید

برای دریافت رویدادها، شما یک منبع چت را برای نظارت مشخص می‌کنید که منبع هدف اشتراک نامیده می‌شود.

رابط برنامه‌نویسی کاربردی رویدادهای فضای کاری گوگل (Google Workspace Events API) از منابع هدف زیر برای چت پشتیبانی می‌کند:

منبع هدف قالب محدودیت‌ها
فضا

//chat.googleapis.com/spaces/ SPACE

که در آن SPACE شناسه در نام منبع مربوط به منبع space Chat API است. می‌توانید شناسه را از URL فضا یا با استفاده از متد spaces.list() به دست آورید.

 کاربر چت یا برنامه چتی که اشتراک را تأیید می‌کند، باید از طریق Google Workspace یا حساب گوگل خود عضو این فضا باشد. پشتیبانی می‌کند از:
تمام فضاهای یک کاربر

//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

برای مثال، برای دریافت رویدادهای مربوط به پیوستن کاربران به یک فضای چت، فضا را به عنوان منبع هدف و نوع رویداد را 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

انواع رویدادهای دسته‌ای (فقط خروجی)

علاوه بر دریافت انواع رویدادهایی که در آنها مشترک می‌شوید، برنامه چت شما ممکن است رویدادهای دسته‌ای را نیز دریافت کند. یک رویداد دسته‌ای رویدادی است که نشان‌دهنده رویدادهای زیادی از یک نوع است که در یک بازه زمانی کوتاه رخ می‌دهند. محتوای یک رویداد دسته‌ای شامل لیستی از تمام منابع تغییر یافته است.

برای مثال، اگر یک کاربر همزمان 20 کاربر را به یک فضا اضافه کند، برنامه چت شما ممکن است یک رویداد دسته‌ای ( google.workspace.chat.membership.v1.batchCreated ) دریافت کند. محتوای رویداد شامل لیستی از تمام منابع Membership جدید است که هنگام اضافه کردن اعضا به فضا توسط کاربر ایجاد شده‌اند.

شما برای هر نوع رویدادی که در آن مشترک شوید، یک رویداد دسته‌ای دریافت می‌کنید، بنابراین هنگام ایجاد اشتراک نیازی به مشخص کردن رویدادهای دسته‌ای ندارید. برای مثال، اگر در واکنش‌های جدید ( google.workspace.chat.reaction.v1.created ) مشترک شوید، برنامه چت شما به طور خودکار برای دریافت رویدادهای واکنش دسته‌ای ( 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 شما رویدادی را از Chat دریافت می‌کند، فیلد data شامل payload مربوط به آن رویداد است. این payload حاوی اطلاعاتی درباره منبع Google Workspace است که تغییر کرده است. برای مثال، اگر در رویدادهای عضویت در یک فضا مشترک شده باشید، payload مربوط به این رویدادها حاوی اطلاعاتی درباره منبع spaces.membership است که تغییر کرده است.

داده‌های منبع در بار داده رویداد

هنگام ایجاد اشتراک، می‌توانید مشخص کنید که آیا می‌خواهید محتوای اشتراک شامل جزئیات مربوط به منبع باشد یا فقط نام منبع. به عنوان مثال، اگر می‌خواهید رویدادهای مربوط به اعضا را در یک فضای چت دریافت کنید، می‌توانید مشخص کنید که می‌خواهید کدام فیلدهای یک منبع عضویت را در محتوای رویداد دریافت کنید.

جدول زیر نمونه‌هایی از داده‌های JSON برای اشتراک در فضای چت spaces/AAAABBBBBB را ارائه می‌دهد. برای هر رویدادی که اشتراک دریافت می‌کند، داده‌های مربوط به آن رویداد در فیلد data نمایش داده می‌شود:

مثال نوع رویداد بار داده JSON

یک کاربر پیامی را در این فضا ارسال می‌کند که می‌گوید «سلام دنیا».

google.workspace.chat.message.v1.created

شامل داده‌های منابع:

{
    "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"
    }
}
یک کاربر مدیر فضا می‌شود.

google.workspace.chat.membership.v1.updated

شامل داده‌های منابع:

{
    "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"
    }
}
یک کاربر توضیحات مربوط به فضا را به «تیم فروش Cymbal Labs» به‌روزرسانی می‌کند. google.workspace.chat.space.v1.updated

شامل داده‌های منابع:

{
    "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"
    }
}
دو کاربر چت همزمان به فضا اضافه شدند. google.workspace.chat.membership.v1.batchCreated

شامل داده‌های منابع:

{
    "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"
          }
        }
    ]
}
یک کاربر با ایموجی 😊 به یک پیام واکنش نشان می‌دهد. google.workspace.chat.reaction.v1.created

شامل داده‌های منابع:

{
    "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"
    }
}
کاربران با ایموجی‌های 😊 و 😸 به یک پیام واکنش نشان می‌دهند. google.workspace.chat.reaction.v1.batchCreated

شامل داده‌های منابع: 

{
    "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 )، فقط پس از ارسال اولین پیام فعال می‌شوند.
  • برای دریافت رویدادهای عضویت، کاربر یا برنامه چت باید عضو مستقیم آن فضا باشند. اگر آنها به طور غیرمستقیم از طریق یک گروه گوگل به یک فضا اضافه، به‌روزرسانی یا حذف شده باشند، اشتراک آن رویدادهای عضویت را دریافت نمی‌کند. برای درک نحوه عملکرد عضویت در گروه گوگل، به افزودن یک گروه گوگل به یک فضا مراجعه کنید.