الإشعارات الفورية في 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 في 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() must be authorized باستخدام رمز تفويض مميز. يجب أن يتضمّن رمز المصادقة هذا نطاق الإشعارات الفورية (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() لإلغاء التسجيل لتلقّي الإشعارات.