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

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

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

چگونه برنامه شما رویدادها را دریافت می کند

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

تصویری از نحوه ارائه رویدادها توسط Google Workspace Events API.
شکل 1. مثالی از نحوه ارائه رویدادها به برنامه Chat توسط Google Workspace Events API.

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

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

اصطلاحات مهم

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

رویداد Google Workspace

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

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

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

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

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

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

منبع هدف رویدادهای پشتیبانی شده
فضاهای چت گوگل
  • پیام ها
  • عضویت ها
  • واکنش ها
  • فضا
کاربران چت گوگل
  • عضویت ها
فضاهای ملاقات Google Meet
  • کنفرانس ها
  • جلسات شرکت کننده
  • ضبط ها
  • رونوشت ها
کاربران Google Meet
  • کنفرانس ها
  • جلسات شرکت کننده
  • ضبط ها
  • رونوشت ها

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

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

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

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

ویژگی های CloudEvent

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

صفت توضیحات مثال

datacontenttype

 نوع داده ای که در رویداد ارسال شده است.

application/json

id

 یک شناسه برای CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

 منبع واقعه. برای رویدادهای Google Workspace، این نام منبع کامل اشتراک است. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

 نسخه مشخصات CloudEvents استفاده شده برای این رویداد.

1.0

subject

 منبع Google Workspace که در آن رویداد رخ داده است.

//chat.googleapis.com/spaces/AAAABBBBBBB

time

 مهر زمانی که رویداد رخ داد، در قالب RFC 3339 .

2023-09-07T21:37:36.260127Z

type

 نوع رویداد Google Workspace.

google.workspace.chat.message.v1.created

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

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

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

وقتی اشتراکی ایجاد می‌کنید، می‌توانید تعیین کنید چه مقدار داده منبع در رویدادهایی که برنامه شما دریافت می‌کند شامل شود:

  • Include Resource Data: شامل برخی یا همه فیلدهای منبع تغییر یافته است. اگر انتخاب می‌کنید داده‌های منبع را اضافه کنید، مدت زمان اشتراک شما به حداکثر 4 ساعت یا 24 ساعت در صورت استفاده از تفویض اختیار در سطح دامنه محدود می‌شود.
  • Exclude Resource Data : فقط شامل نام منبع تغییر یافته است. مدت زمان اشتراک شما تا 7 روز است. برای دریافت جزئیات در مورد رویداد، می توانید منبع را با استفاده از نام منبع جستجو کنید.

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

رویدادها به‌عنوان پیام‌های Google Cloud Pub/Sub

اشتراک‌های Google Workspace Events API از موضوعات 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 Protocol Binding for CloudEvents مراجعه کنید.