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

لإعداد موضوع Cloud Pub/Sub، عليك تنفيذ ما يلي:

  1. احرص على استيفاء المتطلبات الأساسية لخدمة Cloud Pub/Sub.
  2. إعداد برنامج Cloud Pub/Sub
  3. يُرجى مراجعة أسعار Cloud Pub/Sub، وتفعيل الفوترة لمشروع Play Console.

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

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

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

ملاحظة: إذا منحت حساب خدمة "الإشعارات الفورية" إذنًا بالنشر في موضوع Cloud Pub/Sub، سيتم السماح للمستخدمين الذين يمكنهم تقديم طلبات من مشروع "وحدة تحكم المطوّرين" بالتأكد من توفُّره والتسجيل للحصول على إشعارات بشأنه. تخزّن العديد من التطبيقات معرّفات عملاء OAuth من جهة العميل، لذلك قد يتمكن المستخدمون النهائيون من تقديم طلبات من مشروع Developer Console. إذا كان ذلك ينطبق عليك، وكنت قلقًا بشأن إرسال المستخدمين النهائيين لإشعارات غير مرغوب فيها إلى موضوع Cloud Pub/Sub أو معرفة أسماء مواضيع Cloud Pub/Sub التي تستخدمها للإشعارات الفورية، يمكنك التسجيل للحصول على إشعارات فورية من مشروع مختلف على Developer Console.

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

بعد توفُّر موضوع يمكن لحساب خدمة الإشعارات الفورية في 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(). وبالمثل، ستحتوي التغييرات التي يتم إجراؤها على مجموعة passwords.courseWork على الحقول courseId وid التي يمكن إرسالها بدون تعديل إلى courses.courseWork.get() courses.courseWork.get() وزِيهما: courses.courseWork.get() وزِي مهام {studentcourses.learnWork.getwork.requestwork.request to thelessons المجمَّعة. {studentcourse1}إلى تلك التغييرات. courseIdidcourseWorkIdcourses.courseWork.studentSubmissions.get()

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

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

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