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

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

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

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

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

لتلقّي إشعارات فورية، عليك إعداد موضوع 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. تأكَّد من استيفاء متطلبات فسحة النشر/الاشتراك في السحابة الإلكترونية.
  2. إعداد عميل Cloud Pub/Sub
  3. راجِع أسعار Cloud Pub/Sub، وفعِّل الفوترة لمشروعك على Developer Console.

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

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

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

ملاحظة: إذا منحت حساب خدمة الإشعارات الفورية إذن النشر إلى موضوع Cloud Pub/Sub، سيتمكّن المستخدمون الذين يمكنهم تقديم طلبات من مشروع Developer Console من تحديد توفّره والاشتراك لتلقّي الإشعارات عليه. تخزِّن العديد من التطبيقات معرّفات عملاء 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 للمورد المناسب. بالنسبة إلى الإشعارات حول التغييرات في القائمة، سيتمgefülltملء الحقلين 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() لإلغاء التسجيل من الإشعارات.