الإشعارات الفورية في 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() الحصول على إذن لإرسال طلبات البيانات إلى 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() لإلغاء التسجيل في الإشعارات.