تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الإشعارات الفورية في 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، عليك إجراء ما يلي:

تأكَّد من استيفاء المتطلبات الأساسية لخدمة Cloud Pub/Sub.
إعداد برنامج Cloud Pub/Sub.
يمكنك مراجعة أسعار Cloud Pub/Sub وتمكين الفوترة لمشروع وحدة تحكم مطوّر البرامج.
يمكنك إنشاء موضوع Cloud Pub/Sub في Developer Console (الطريقة الأسهل)، أو من خلال أداة سطر الأوامر (للاستخدام الآلي البسيط) أو استخدام Cloud Pub/Sub API. لاحظ أن خدمة Cloud Pub/Sub لا تسمح إلا بعدد محدود من المواضيع، لذا فإن استخدام موضوع واحد لتلقي جميع الإشعارات يضمن لك عدم الوقوع في مشاكل تحجيم إذا أصبح تطبيقك شائعًا.
أنشئ اشتراكًا في Cloud Pub/Sub، لإخبار Cloud Pub/Sub بكيفية عرض الإشعارات.
وأخيرًا، قبل التسجيل في الإشعارات الفورية، يلزمك منح حساب خدمة الإشعارات الفورية (classroom-notifications@system.gserviceaccount.com) إذنًا للنشر في موضوعك.

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

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

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

التفويض

مثل جميع الطلبات إلى واجهة برمجة تطبيقات Classroom، يجب تخويل المكالمات إلى registrations.create() باستخدام رمز التفويض المميز. يجب أن يتضمن الرمز المميز للمصادقة نطاق Push Notifications (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 من المستخدم المفوض باستخدام النطاقات المطلوبة. إذا قطع المستخدم اتصال التطبيق، فستتوقف الإشعارات. تجدر الإشارة إلى أن تفويض التفويض على مستوى النطاق غير متاح حاليًا لهذا الغرض. وإذا حاولت التسجيل في الإشعارات باستخدام تفويض مفوَّض على مستوى النطاق فقط، ستتلقّى رسالة الخطأ "`@GrantGrant".

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

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

اسم المجموعة التي تحتوي على المورد الذي تم تغييره. بالنسبة إلى الإشعارات حول تغييرات قائمة الطلاب المسجّلين، يمكنك مراجعة courses.students أو courses.teachers. بالنسبة إلى تغييرات العمل في الدورة التدريبية، تكون القيمة إما courses.courseWork أو courses.courseWork.studentSubmissions.
معرّفات المورد الذي تم تغييره في خريطة تم تصميم هذه الخريطة لمطابقة الوسيطات مع طريقة get من المورد المناسب. بالنسبة إلى الإشعارات حول تغييرات قائمة الطلاب المسجّلين، ستتم تعبئة الحقلين courseId وuserId، ويمكن إرسالهما بدون تعديل إلى courses.students.get() أو courses.teachers.get(). وبالمثل، ستتضمن التغييرات في مجموعة path.courseWork courseId وid الحقلين اللذين يمكن إرسالهما بدون تعديل إلى .course.course.student.course.student.event.event.event.event.to.event.event.to.edu.satod.has.tod.has.tod.has.to. ترغب في}.

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

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

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