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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

تسمح ميزة الإشعارات الفورية في Classroom API للتطبيقات التي تستخدم Classroom API للاشتراك في الإشعارات عند تغيُّر البيانات في Classroom. يتم تسليم الإشعارات إلى 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 لا يسمح إلا بعدد محدود من topics، لذا فإنّ استخدام موضوع واحد لتلقّي جميع إشعاراتك يضمن عدم مواجهة مشاكل في التوسّع إذا أصبح تطبيقك رائجًا.

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

6. وأخيرًا، قبل التسجيل في خدمة الإشعارات الفورية، يجب منح حساب خدمة الإشعارات الفورية ([email protected]) إذن لـ لنشره على موضوعك

ملاحظة: إذا منحت حساب خدمة الإشعارات الفورية إذن النشر إلى موضوع Cloud Pub/Sub، سيتمكّن المستخدمون الذين يمكنهم تقديم طلبات من مشروعك على Developer Console من معرفة أنّه متوفّر، والاشتراك لتلقّي الإشعارات عليه. تخزِّن العديد من التطبيقات معرّفات عملاء OAuth على العميل. حتى يتمكن المستخدمون النهائيون من تقديم طلبات من خلال Play Console مشروعك. إذا كان ذلك ينطبق عليك، وكنت قلقًا بشأن إرسال المستخدمين النهائيين الإشعارات غير المرغوب فيها بشأن موضوع Cloud Pub/Sub أو معرفة أسماء Cloud مواضيع النشر/الاشتراك التي تستخدمها للإشعارات الفورية، لذا يجب أخذها في الاعتبار التسجيل لتلقّي إشعارات فورية من مشروع مختلف على Play 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(). وبالمثل، سيكون للتغييرات التي يتم إجراؤها على مجموعة session.courseWork الحقلان courseId وid اللذين يمكن إرسالهما بدون تعديل إلى courses.courseWork.get() والتغييرات التي يتم إجراؤها على مجموعة session.courseWork.studentSubmissions ستتغير تحتوي على حقول courseId وcourseWorkId وid يمكن إرسالها بدون تعديل. إلى courses.courseWork.studentSubmissions.get().

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

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

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