الاشتراك في الفعاليات باستخدام 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" للأحداث إلى تطبيق 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 Drive
• الاشتراك في أحداث Google Meet

بنية أحداث Google Workspace

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

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

يوضّح القسم التالي بنية السمات والبيانات الخاصة بفعاليات Google Workspace.

سمات CloudEvent

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

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

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

على سبيل المثال، إذا كان لديك اشتراك في مساحة 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.

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

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

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