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

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

  1. يشترك تطبيقك في مرجع في أحد تطبيقات Google Workspace، مثل مساحة Google Chat.
  2. يتغيّر المورد الذي اشتركت فيه.
  3. يعرض تطبيق Google Workspace حدثًا حول موضوع في Google Cloud Pub/Sub، ويعمل كنقطة نهاية الإشعارات لاشتراكك في Google Workspace. يحتوي الحدث على بيانات حول ما تغير في المورد.
  4. يعالج تطبيقك رسالة 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 //chat.googleapis.com/spaces/SPACE_ID
  • الرسائل
  • العضويات
  • التفاعلات
  • المساحة

لمعرفة التفاصيل، يمكنك الاطّلاع على مقالة الاشتراك في أحداث 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 مواصفات CloudEvent، وهي طريقة معيارية في المجال لوصف بيانات الفعاليات. تحتوي أحداث 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

تمثّل هذه السمة إصدار مواصفات CloudEvent المستخدَم لهذا الحدث.

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 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.

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