الاشتراك في الفعاليات باستخدام Google Workspace Events API

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

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

كيفية تلقّي تطبيقك للأحداث

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

صورة توضيحية لكيفية عرض الأحداث في Google Workspace Events API
الشكل 1. مثال على كيفية استجابة توفّر Google Workspace Events API الأحداث تطبيق Chat

في المثال التالي، إليك طريقة توفير واجهة برمجة التطبيقات Google Workspace Events API الأحداث إلى تطبيق Google Chat من خلال اشتراك:

  1. يشترك تطبيق Chat في "مساحة Chat".
  2. سيتم تغيير "مساحة Chat". على سبيل المثال، يتم نشر رسالة جديدة في الفضاء.
  3. يعمل تطبيق Chat على تسليم حدث إلى موضوع في . Google Cloud Pub/Sub، والتي تعمل كنقطة نهاية للإشعار للاشتراك. الفعالية يحتوي على بيانات حول ما تم تغييره. على سبيل المثال، إذا كان الحدث حول حدث جديد فإن الحدث يحتوي على تفاصيل حول مورد Message الذي يمثل إنشاء.
  4. يعالج تطبيق Chat حساب Google Cloud. رسالة نشر/اشتراك تحتوي على الحدث، واتخاذ إجراء إذا لزم الأمر.

مصطلحات مهمة

في ما يلي قائمة بالمصطلحات الشائعة المستخدمة في واجهة برمجة التطبيقات لفعاليات Google Workspace:

فعالية Google Workspace

تغيير إلى مورد Google Workspace يتم تنسيق الأحداث باستخدام ملف CloudEvents وقد تكون إما حدث اشتراك أو حدث في مراحل النشاط:

حدث الاشتراك
تغيير في مورد Google Workspace الذي تراقبه، مثل رسالة جديدة في مساحة Google Chat يمكنك تحديد مقدار التفاصيل التي تريد الحصول عليها حول المورد الذي تم تغييره. للحصول على التفاصيل، يُرجى مراجعة بنية أحداث Google Workspace:
حدث من مراحل النشاط
حدث حول اشتراكك في Google Workspace أحداث مراحل النشاط إشعارك بالمشاكل وحالة اشتراكك كي تتمكّن من لتجنُّب فقدان أحداث الاشتراك بشكل تلقائي، يظل اشتراكك يتلقّى أحداثًا في مراحل النشاط لمزيد من التفاصيل، يُرجى الاطّلاع على أحداث مراحل نشاط اشتراكات Google Workspace.
اشتراك Google Workspace

يشير هذا المصطلح إلى كيان معيَّن يراقب موردًا من Google Workspace. التطبيق. يتم تمثيل الاشتراك Subscription المصدر. يتم تحديد الاشتراك من خلال المعلومات التالية:

المورد المستهدف
مورد Google Workspace الذي تريد مراقبته يتم تمثيل هذا المورد في الحقل targetResource من في Google Workspace. يمكن لكل اشتراك فقط لمراقبة مورد واحد. لمعرفة موارد Google Workspace التي تتيح لك Google Workspace Events API الاطّلاع على أحداث Google Workspace المتوافقة.
أنواع الأحداث
أنواع التغييرات التي تريد تلقّي إشعارات بشأنها المورد المستهدف. على سبيل المثال، إذا اشتركت في في مساحة Google Chat، يمكنك اختيار ما إذا كنت تريد تلقّي أحداث حول المساحة ومواردها الفرعية، مثل العضويات والرسائل
نقطة نهاية الإشعار
نقطة النهاية حيث يتلقّى اشتراك Google Workspace الأحداث. تشير رسالة الأشكال البيانية تتيح واجهة Google Workspace Events API استخدام مواضيع Google Cloud Pub/Sub على النحو التالي: نقطة نهاية الإشعار. لمزيد من المعلومات عن استخدام Google Cloud Pub/Sub، اطّلِع على مستندات Google Cloud Pub/Sub:
خيارات الحمولة
بيانات الأحداث التي تريد تلقّيها حول الموارد التي تم تغييرها.

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

تعتمد الأحداث التي يمكن لتطبيقك أن يتلقّاها تطبيقك على المورد المستهدَف اشتراكك. يعرض الجدول التالي الأحداث المتوافقة لكلّ المورد المستهدف المحتمل.

المورد المستهدف الأحداث المتوافقة
مساحات Google Chat
  • الرسائل
  • العضويات
  • التفاعلات
  • مسافة
مستخدمو Google Chat
  • العضويات
مساحات اجتماعات Google Meet
  • مؤتمرات
  • جلسات المشاركين
  • التسجيلات
  • ملفات النص
مستخدمو Google Meet
  • مؤتمرات
  • جلسات المشاركين
  • التسجيلات
  • ملفات النص

لمزيد من المعلومات، يمكنك الاطّلاع على الأدلة التالية:

بنية أحداث Google Workspace

تتابع فعاليات Google Workspace فعاليات Cloudفعاليات والمواصفات وهي طريقة متوافقة مع معايير الصناعة لوصف بيانات الأحداث. حساب Google Workspace تحتوي الأحداث على ما يلي:

  • سمات حدث CloudEvent
  • البيانات حول مورد Google Workspace الذي تغيّر نتيجة الحدث

يوضح القسم التالي بنية التصنيفات والبيانات أحداث Google Workspace.

سمات CloudEvent

تحتوي أحداث Google Workspace على ما يلي مطلوب سمات Cloud Events:

السمة الوصف مثال

datacontenttype

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

application/json

id

معرّف لـ CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

مصدر الحدث. بالنسبة إلى فعاليات Google Workspace: هذا هو اسم المورد الكامل للاشتراك. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

إصدار مواصفات Cloudالأحداث المُستخدَم لهذا الحدث

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).

عند إنشاء اشتراك، يمكنك تحديد مقدار بيانات الموارد مضمّنة في الأحداث التي يتلقّاها تطبيقك:

  • تضمين بيانات الموارد: يحتوي على بعض أو كل حقول التغيير الذي تم تغييره المصدر. إذا اخترت تضمين بيانات الموارد، لن تقتصر المدة على 4 ساعات، أو 24 ساعة في حال استخدام على مستوى النطاق التفويض.
  • استبعاد بيانات الموارد: يحتوي هذا الحقل على اسم المستخدم الذي تم تغييره فقط. المصدر. قد تصل مدة اشتراكك إلى 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 تحتوي على حدث حول رسالة معدَّلة في "مساحة Chat":

 {
    "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.