تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الاشتراك في الفعاليات باستخدام 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 من خلال اشتراك:

يشترك تطبيق Chat في "مساحة Chat".
سيتم تغيير "مساحة Chat". على سبيل المثال، يتم نشر رسالة جديدة في الفضاء.
يعرض تطبيق Chat حدثًا لموضوع في . Google Cloud Pub/Sub، والتي تعمل كنقطة نهاية للإشعار للاشتراك. الفعالية يحتوي على بيانات حول ما تم تغييره. على سبيل المثال، بالنسبة إلى حدث حول حدث جديد فإن الحدث يحتوي على تفاصيل حول مورد Message الذي يمثل إنشاء.
يعالج تطبيق 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	للاشتراك في مساحة محدَّدة: `//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 على ما يلي مطلوب سمات 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.

الاشتراك في أحداث Google Chat
الأحداث في مراحل النشاط لاشتراكات Google Workspace
اختيار نطاقات Google Workspace Events API
إنشاء اشتراك Google Workspace