الاشتراك في الفعاليات باستخدام 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 Pub/Sub التي تتضمن الحدث، ويتخذ الإجراء اللازم إذا لزم الأمر.

مصطلحات مهمة

في ما يلي قائمة بالمصطلحات الشائعة المُستخدَمة في Google Workspace Events API:

فعالية 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

للاشتراك في مساحة محدَّدة:

//chat.googleapis.com/spaces/SPACE_ID

للاشتراك في جميع المساحات التي يكون المستخدم عضوًا فيها:

//chat.googleapis.com/spaces/-
  • الرسائل
  • العضويات
  • التفاعلات
  • المساحة

لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة الاشتراك في أحداث Google Chat.		 يجب أن يكون مستخدم Google Chat الذي يسمح بالاشتراك عضوًا في المساحة من خلال حسابه على Google Workspace أو Google.
مستخدمو Google Chat //cloudidentity.googleapis.com/users/USER_ID
  • العضويات

لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة الاشتراك في أحداث Google Chat.

لا يتلقّى الاشتراك إلا الأحداث المتعلقة بالمستخدم الذي فوَّض الاشتراك. لا يمكن للمستخدم تفويض اشتراك نيابةً عن مستخدمين آخرين.
Google Meet
مساحات اجتماعات Google Meet //meet.googleapis.com/spaces/SPACE_ID
  • مؤتمرات
  • جلسات المشاركين
  • التسجيلات
  • الصوت المحوَّل إلى نص

لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة الاشتراك في أحداث Google Meet.
مستخدمو Google Meet //cloudidentity.googleapis.com/users/USER_ID
  • مؤتمرات
  • جلسات المشاركين
  • التسجيلات
  • الصوت المحوَّل إلى نص

لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة الاشتراك في أحداث Google Meet.

يتلقّى الاشتراك أحداثًا حول مساحات الاجتماعات التي يكون فيها المستخدم واحدًا مما يلي:

  • مالك مساحة الاجتماعات
  • منظِّم حدث "تقويم Google" المرتبط بمساحة الاجتماع.

بنية أحداث Google Workspace

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

  • سمات حدث CloudEvent
  • بيانات حول مورد 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

إصدار مواصفات 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 Chat الذي تم إنشاؤه.

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

  • تضمين بيانات الموارد: يحتوي على بعض أو كل حقول المورد الذي تم تغييره. في حال اختيار تضمين بيانات الموارد، تقتصر مدة اشتراكك على 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.

لمعرفة مزيد من المعلومات عن طريقة تحديد Cloudالأحداث في رسائل Google Cloud Pub/Sub، يمكنك الاطّلاع على مقالة ربط بروتوكول Google Cloud Pub/Sub تابعة لـ Cloud Events.