با استفاده از Google Workspace Events API در رویدادها مشترک شوید

این صفحه مروری بر API رویدادهای Google Workspace ارائه می‌دهد و توضیح می‌دهد که چگونه می‌توانید از API برای اشتراک در رویدادها در Google Workspace استفاده کنید.

رویدادهای Google Workspace نشان‌دهنده تغییراتی در منابع Google Workspace هستند، مانند زمانی که منابع ایجاد، به‌روزرسانی یا حذف می‌شوند. برنامه شما می‌تواند در یک منبع Google Workspace مشترک شود تا شما رویدادهای مرتبطی را که به آنها علاقه دارید دریافت کنید.

نحوه دریافت رویدادها توسط برنامه شما

برای اینکه برنامه شما رویدادهای Google Workspace را دریافت کند، از API رویدادهای Google Workspace برای ایجاد اشتراک در منابع Google Workspace استفاده می‌کنید.

در مثال زیر، نحوه‌ی ارائه‌ی رویدادها توسط API رویدادهای Google Workspace به یک برنامه‌ی Google Chat از طریق اشتراک را مشاهده می‌کنید:

1. یک برنامه چت در یک فضای چت مشترک می‌شود.
2. فضای چت تغییر می‌کند. برای مثال، یک پیام جدید در این فضا ارسال می‌شود.
3. چت، رویدادی را به موضوعی در Google Cloud Pub/Sub ارسال می‌کند که به عنوان نقطه پایانی اعلان برای اشتراک عمل می‌کند. این رویداد حاوی داده‌هایی در مورد آنچه تغییر کرده است، می‌باشد. به عنوان مثال، برای رویدادی در مورد یک پیام جدید، این رویداد حاوی جزئیاتی در مورد منبع Message ایجاد شده است.
4. برنامه چت، پیام Google Cloud Pub/Sub که حاوی رویداد است را پردازش می‌کند و در صورت لزوم، اقداماتی را انجام می‌دهد.

اصطلاحات مهم

در زیر لیستی از اصطلاحات رایج مورد استفاده در Google Workspace Events API آمده است:

رویداد گوگل ورک اسپیس

تغییری در منبع Google Workspace. رویدادها با استفاده از مشخصات CloudEvents قالب‌بندی می‌شوند و می‌توانند یک رویداد اشتراک یا یک رویداد چرخه عمر باشند:

رویداد اشتراک

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

رویداد چرخه حیات

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

اشتراک گوگل ورک اسپیس

یک موجودیت نامگذاری شده که منبعی از برنامه Google Workspace را رصد می‌کند. اشتراک با یک منبع Subscription نمایش داده می‌شود. اشتراک با اطلاعات زیر تعریف می‌شود:

منبع هدف

منبع Google Workspace که می‌خواهید مانیتور کنید. این منبع در فیلد targetResource از اشتراک Google Workspace نمایش داده می‌شود. هر اشتراک فقط می‌تواند یک منبع را مانیتور کند. برای مشاهده اینکه API رویدادهای Google Workspace از کدام منابع Google Workspace پشتیبانی می‌کند، به رویدادهای پشتیبانی‌شده Google Workspace مراجعه کنید.

انواع رویداد

انواع تغییراتی که می‌خواهید در مورد منبع هدف از آنها مطلع شوید. به عنوان مثال، اگر در یک فضای چت گوگل مشترک شده‌اید، می‌توانید انتخاب کنید که آیا رویدادهای مربوط به آن فضا و منابع فرزند آن، مانند عضویت‌ها و پیام‌ها، را دریافت کنید یا خیر.

نقطه پایانی اعلان

نقطه پایانی که اشتراک Google Workspace رویدادها را دریافت می‌کند. API رویدادهای Google Workspace از موضوعات Google Cloud Pub/Sub به عنوان نقطه پایانی اعلان پشتیبانی می‌کند. برای کسب اطلاعات بیشتر در مورد استفاده از Google Cloud Pub/Sub، به مستندات Google Cloud Pub/Sub مراجعه کنید.

گزینه‌های بار مفید

داده‌های رویدادی که می‌خواهید در مورد منابع تغییر یافته دریافت کنید.

رویدادهای پشتیبانی‌شده‌ی Google Workspace

رویدادهایی که برنامه شما می‌تواند دریافت کند، به منبع هدف اشتراک شما بستگی دارد. جدول زیر رویدادهای پشتیبانی شده برای هر منبع هدف ممکن را نشان می‌دهد.

برای کسب اطلاعات بیشتر، به راهنماهای زیر مراجعه کنید:

• در رویدادهای گوگل چت مشترک شوید
• در رویدادهای گوگل درایو مشترک شوید
• در رویدادهای گوگل میت مشترک شوید

ساختار رویدادهای Google Workspace

رویدادهای Google Workspace از مشخصات CloudEvents پیروی می‌کنند که یک روش استاندارد صنعتی برای توصیف داده‌های رویداد است. رویدادهای Google Workspace شامل موارد زیر هستند:

• ویژگی‌های رویداد ابری (CloudEvent).
• داده‌های مربوط به منبع Google Workspace که در نتیجه رویداد تغییر کرده‌اند

بخش زیر ساختار ویژگی‌ها و داده‌های رویدادهای Google Workspace را توضیح می‌دهد.

ویژگی‌های CloudEvent

رویدادهای Google Workspace شامل ویژگی‌های CloudEvents مورد نیاز زیر هستند:

داده‌های رویداد

داده‌های رویداد، یک بار داده (payload) است که نشان‌دهنده‌ی تغییر در منبع هدف اشتراک شما، از جمله منابع فرزند منبع هدف، می‌باشد. در اشتراک خود، می‌توانید مشخص کنید که آیا می‌خواهید بار داده شامل داده‌های مربوط به منبع تغییر یافته باشد یا فقط نام منبع تغییر یافته.

برای مثال، اگر در یک فضای چت اشتراک دارید، می‌توانید رویدادهای مربوط به پیام‌های جدید را در آن فضا دریافت کنید. برای رویدادهای مربوط به پیام‌های جدید، داده‌های رویداد شامل یک payload با منبع Chat spaces.message است که ایجاد شده است.

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

این گزینه‌ها برای داده‌های رویداد در فیلد payloadOptions اشتراک شما نمایش داده می‌شوند.

رویدادها به عنوان پیام‌های Pub/Sub گوگل کلود

اشتراک‌های API رویدادهای Google Workspace از موضوعات Google Cloud Pub/Sub به عنوان نقطه پایانی اعلان که رویدادهای Google Workspace را دریافت می‌کند، استفاده می‌کنند. رویدادها به صورت پیام‌های Google Cloud Pub/Sub کدگذاری می‌شوند. برنامه شما می‌تواند پیام Google Cloud Pub/Sub را برای انجام اقدام یا پاسخ به رویداد پردازش کند.

مثال زیر یک پیام Google Cloud Pub/Sub را نشان می‌دهد که حاوی رویدادی درباره یک پیام به‌روزرسانی‌شده در یک فضای چت است:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

به فیلدهای زیر توجه کنید:

• attributes : ویژگی‌هایی برای CloudEvent که شامل نوع رویداد می‌شود. در این مورد، رویداد مربوط به یک پیام به‌روزرسانی‌شده در فضا است.
• data : داده‌های رویداد به همراه جزئیاتی در مورد منبع به‌روزرسانی‌شده‌ی spaces.message ، که به صورت یک رشته‌ی کدگذاری‌شده با Base64 قالب‌بندی شده است.
• messageId : شناسه‌ی پیام Google Cloud Pub/Sub.

برای کسب اطلاعات بیشتر در مورد نحوه مشخص شدن CloudEvents در پیام‌های Google Cloud Pub/Sub، به بخش اتصال پروتکل Google Cloud Pub/Sub برای CloudEvents مراجعه کنید.

مباحث مرتبط

• انتخاب محدوده‌های API رویدادهای Google Workspace
• ایجاد اشتراک Google Workspace