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

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

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

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

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

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

1. يشترك تطبيق Chat في مساحة Google 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 الذي تراقب نشاطه، مثل رسالة جديدة في مساحة 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 المتوافقة.

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

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

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

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

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

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

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

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

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

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

بنية أحداث Google Workspace

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

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

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

سمات CloudEvent

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

بيانات الأحداث

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

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

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

يتم تمثيل خيارات بيانات الأحداث هذه في حقل 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 بـ CloudEvents.

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

• اختيار نطاقات Google Workspace Events API
• إنشاء اشتراك في Google Workspace