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

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

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

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

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

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

في المثال التالي، إليك كيفية إرسال "واجهة برمجة تطبيقات أحداث Google Workspace" للأحداث إلى تطبيق 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
  • العضويات
مساحات الاجتماعات في 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، يمكنك تلقّي أحداث حول الرسائل الجديدة في المساحة. بالنسبة إلى الأحداث المتعلّقة بالرسائل الجديدة، تحتوي بيانات الحدث على حمولة تحتوي على مورد Chat spaces.message الذي تم إنشاؤه.

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

  • تضمين بيانات المورد: يحتوي على بعض حقول المورد المتغيّر أو كلّها. إذا اخترت تضمين بيانات الموارد، تقتصر مدّة اشتراكك على 4 ساعات كحد أقصى، أو 24 ساعة إذا كنت تستخدم تفويضًا على مستوى النطاق.
  • استبعاد بيانات المورد: يحتوي على اسم المورد الذي تم تغييره فقط. تبلغ مدة الاشتراك 7 أيام كحد أقصى. للحصول على تفاصيل عن الحدث، يمكنك طلب البحث عن المورد باستخدام اسم المورد.

يتم تمثيل خيارات بيانات الأحداث هذه في حقل payloadOptions في اشتراكك.

الأحداث كرسائل في Google Cloud Pub/Sub

تستخدِم الاشتراكات في "واجهة برمجة تطبيقات أحداث Google Workspace" مواضيع 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 بأحداث CloudEvents.