الإشعارات الفورية في Classroom API

يمكنك استخدام الطرق المتاحة في مجموعة Registrations لتلقّي إشعارات عند حدوث تغييرات في بيانات Classroom.

تقدّم هذه المقالة نظرة عامة مفاهيمية بالإضافة إلى تعليمات بسيطة حول كيفية البدء في تلقّي الإشعارات الفورية.

نظرة عامة على الإشعارات الفورية في Classroom

تتيح ميزة الإشعارات الفورية في Classroom API للتطبيقات التي تستخدم Classroom API الاشتراك في تلقّي إشعارات عند حدوث تغييرات في بيانات Classroom. يتم تسليم الإشعارات إلى موضوع Cloud Pub/Sub، عادةً في غضون بضع دقائق من إجراء التغيير.

لتلقّي إشعارات فورية، عليك إعداد موضوع في Cloud Pub/Sub وتقديم اسم هذا الموضوع عند إنشاء تسجيل لخلاصة الإشعارات المناسبة.

في ما يلي تعريفات للمفاهيم الرئيسية المستخدَمة في هذه المستندات:

• الوجهة هي المكان الذي يتم إرسال الإشعارات إليه.
• الخلاصة هي نوع من الإشعارات يمكن أن يشترك فيه تطبيق تابع لجهة خارجية. على سبيل المثال، "تغييرات قائمة الطلاب في الصف 1234".
• التسجيل هو تعليمات إلى Classroom API لإرسال إشعارات من خلاصة معيّنة إلى وجهة.

بعد إنشاء تسجيل لخلاصة، يتلقّى موضوع Cloud Pub/Sub الخاص بهذا التسجيل إشعارات من تلك الخلاصة إلى أن تنتهي صلاحيته. تستمر فترة التسجيل لمدة أسبوع، ولكن يمكنك تمديدها في أي وقت قبل انتهائها من خلال تقديم طلب مماثل إلى registrations.create().

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

أنواع الخلاصات

توفّر Classroom API ثلاثة أنواع من الخلاصات:

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

إعداد موضوع Cloud Pub/Sub

يتم إرسال الإشعارات إلى مواضيع Cloud Pub/Sub. من Cloud Pub/Sub، يمكنك تلقّي إشعارات على Webhook، أو عن طريق طلب البيانات بشكل متكرّر من نقطة نهاية الاشتراك.

لإعداد موضوع Cloud Pub/Sub، عليك اتّباع الخطوات التالية:

1. تأكَّد من استيفاء متطلبات Cloud Pub/Sub.
2. إعداد عميل Cloud Pub/Sub
3. راجِع أسعار Cloud Pub/Sub، وفعِّل الفوترة لمشروعك على Developer Console.

4. أنشئ موضوعًا في Cloud Pub/Sub في Developer Console (الأسهل) أو عبر أداة سطر الأوامر (للاستخدام البرمجي البسيط) أو باستخدام Cloud Pub/Sub API. يُرجى العِلم أنّ Cloud Pub/Sub لا يسمح إلا بعدد محدود من المواضيع، لذا فإنّ استخدام موضوع واحد لتلقّي جميع إشعاراتك يضمن عدم مواجهة مشاكل في التوسّع إذا أصبح تطبيقك رائجًا.

5. أنشئ اشتراكًا في Cloud Pub/Sub لتحديد كيفية تسليم الإشعارات في Cloud Pub/Sub.

6. أخيرًا، قبل التسجيل في خدمة "الإشعارات الفورية"، عليك منح حساب خدمة الإشعارات الفورية (classroom-notifications@system.gserviceaccount.com) إذنًا بالنشر في موضوعك.

تسجيل تطبيقك لتلقّي الإشعارات

بعد الحصول على موضوع يمكن لحساب خدمة الإشعارات الفورية في Classroom API نشره، يمكنك التسجيل لتلقّي الإشعارات باستخدام الطريقة registrations.create(). تتحقّق الطريقة registrations.create() من إمكانية وصول حساب خدمة الإشعارات الفورية إلى موضوع Cloud Pub/Sub المقدَّم. يتعذّر تنفيذ الطريقة إذا لم يتمكّن حساب خدمة الإشعارات الفورية من الوصول إلى الموضوع، مثلاً إذا كان الموضوع غير متوفّر أو إذا لم تمنحه إذن النشر في هذا الموضوع.

التفويض

مثل جميع طلبات البيانات من Classroom API، يجب registrations.create() تفويض طلبات البيانات من خلال رمز تفويض مميز. يجب أن تتضمّن رمز المصادقة هذا نطاق الإشعارات الفورية (https://www.googleapis.com/auth/classroom.push-notifications) وأي نطاقات أخرى مطلوبة لعرض البيانات التي يتم إرسال الإشعارات بشأنها.

• بالنسبة إلى خلاصات تغيير قوائم اللاعبين، يعني ذلك نطاق "قوائم اللاعبين" أو (من المفترض) نوعه للقراءة فقط (https://www.googleapis.com/auth/classroom.rosters.readonly أو https://www.googleapis.com/auth/classroom.rosters).
• بالنسبة إلى خلاصات التغيير الخاصة بالمهام الدراسية، يعني ذلك إصدارات "الطلاب" لنطاق المهمة الدراسية أو (من المفترض) الإصدار المخصّص للقراءة فقط (https://www.googleapis.com/auth/classroom.coursework.students.readonly أو https://www.googleapis.com/auth/classroom.coursework.students).

لكي يتم تسليم الإشعارات، يجب أن يحتفظ التطبيق بمنح الإذن باستخدام OAuth من المستخدم المفوَّض بالنطاقات المطلوبة. إذا قطع المستخدم اتصال التطبيق، ستتوقف الإشعارات. يُرجى العِلم أنّه لا يمكن حاليًا تفويض السلطة على مستوى النطاق لهذا الغرض. إذا حاولت التسجيل لتلقّي الإشعارات باستخدام التفويض على مستوى النطاق فقط، ستتلقّى رسالة الخطأ @MissingGrant.

تلقّي إشعارات

يتم ترميز الإشعارات باستخدام JSON، وهي تتضمّن ما يلي:

• اسم المجموعة التي تحتوي على المورد الذي تم تغييره بالنسبة إلى الإشعارات بشأن التغييرات في قائمة المشاركين، تكون القيمة إما courses.students أو courses.teachers. بالنسبة إلى تغييرات العمل في الدورة التدريبية، تكون القيمة إما courses.courseWork أو courses.courseWork.studentSubmissions.
• معرّفات المورد الذي تم تغييره، في خريطة تم تصميم هذه الخريطة لمطابقة الوسيطات مع طريقة get الخاصة بالمرجع المناسب. بالنسبة إلى الإشعارات بشأن التغييرات في قوائم الطلاب، سيتم ملء الحقلَين courseId وuserId، ويمكن إرسالهما بدون تعديل إلى courses.students.get() أو courses.teachers.get(). وبالمثل، ستتضمّن التغييرات في مجموعة courses.courseWork الحقلَين courseId وid اللذين يمكن إرسالهما بدون تعديل إلى courses.courseWork.get()، وستتضمّن التغييرات في مجموعة courses.courseWork.studentSubmissions الحقول courseId وcourseWorkId وid التي يمكن إرسالها بدون تعديل إلى courses.courseWork.studentSubmissions.get().

يوضّح مقتطف الرمز التالي نموذج إشعار:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

تحتوي الإشعارات أيضًا على سمة الرسالة registrationId التي تتضمّن المعرّف الخاص بالتسجيل الذي أدّى إلى ظهور الإشعار، ويمكن استخدامها مع registrations.delete() لإلغاء التسجيل في الإشعارات.