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

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

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

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

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

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

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

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

المصطلحات المهمة

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

حدث Google Workspace

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

حدث الاشتراك

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

حدث يتم في مراحل النشاط

حدث حول اشتراك Google Workspace. تُعلمك أحداث دورة الحياة بالمشاكل وحالة اشتراكك حتى تتمكّن من تجنُّب فقدان أحداث الاشتراك. تتلقّى دائمًا أحداث دورة الحياة في اشتراكك بشكل تلقائي. لمعرفة التفاصيل، يُرجى الاطّلاع على أحداث دورة الحياة للاشتراكات في Google Workspace.

اشتراك Google Workspace

كيان مُسمّى يراقب أحد الموارد من أحد تطبيقات Google Workspace. يتم تمثيل الاشتراك من خلال مورد Subscription. يتم تحديد الاشتراك من خلال المعلومات التالية:

المورد المستهدف

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

أنواع الأحداث

أنواع التغييرات التي تريد تلقّي إشعارات بشأنها للمورد المستهدف. على سبيل المثال، إذا اشتركت في مساحة Chat، يمكنك اختيار ما إذا كنت تريد تلقّي أحداث حول المساحة والموارد الفرعية التابعة لها، مثل العضويات والرسائل.

نقطة نهاية الإشعارات

نقطة النهاية التي يتلقّى فيها اشتراك Google Workspace الأحداث. تتوافق واجهة برمجة تطبيقات أحداث Google Workspace مع مواضيع Google Cloud Pub/Sub كنقطة نهاية للإشعارات. لمزيد من المعلومات حول استخدام Google Cloud Pub/Sub، يُرجى الاطّلاع على مستندات Google Cloud Pub/Sub.

خيارات الحمولة

بيانات الأحداث التي تريد تلقّيها حول الموارد التي تم تغييرها.

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

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

المورد المستهدف	الأحداث المتوافقة
مساحات Chat	الرسائل العضويات التفاعلات مسافة
مستخدمو Chat	العضويات حالة القراءة ( إصدار المعاينة للمطوّرين)
ملفات Google Drive أو الملفات في مساحة تخزين سحابي مشتركة في Google Drive	اقتراحات الوصول الموافقات التعليقات الملفات الردود
مساحات اجتماعات Google Meet والمستخدمون	مؤتمرات جلسات المشاركين التسجيلات الملاحظات الذكية الصوت المحوَّل إلى نص

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

• الاشتراك في أحداث Chat
• الاشتراك في أحداث Drive
• الاشتراك في أحداث Meet

بنية أحداث Google Workspace

تتّبع أحداث Google Workspace مواصفات CloudEvents، وهي طريقة معتمَدة في المجال لوصف بيانات الأحداث. تحتوي أحداث 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	إصدار مواصفات 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: بيانات الحدث التي تحتوي على تفاصيل حول مورد الذي تم تعديله، بتنسيق سلسلة بترميز Base64.spaces.message
• messageId: معرّف رسالة Google Cloud Pub/Sub

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

مواضيع ذات صلة

• اختيار نطاقات واجهة برمجة تطبيقات أحداث Google Workspace
• إنشاء اشتراك في Google Workspace