تتوفّر الآن إضافات Google Classroom بشكل عام للمطوّرين. يُرجى الاطّلاع على مستندات الإضافات للحصول على مزيد من المعلومات.

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

الإشعارات الفورية في 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، عليك اتّباع الخطوات التالية:

تأكَّد من استيفاء متطلبات فسحة النشر/الاشتراك في السحابة الإلكترونية.
إعداد عميل Cloud Pub/Sub
راجِع أسعار Cloud Pub/Sub، وفعِّل الفوترة لمشروعك على Developer Console.
أنشئ موضوعًا في Cloud Pub/Sub في "وحدة تحكّم المطوّر" (أسهل طريقة) أو من خلال أداة سطر الأوامر (للاستخدام الآلي البسيط) أو باستخدام واجهة برمجة تطبيقات Cloud Pub/Sub. يُرجى العِلم أنّ Cloud Pub/Sub لا يسمح إلا بعدد محدود من topics، لذا فإنّ استخدام موضوع واحد لتلقّي جميع إشعاراتك يضمن عدم مواجهة مشاكل في التوسّع إذا أصبح تطبيقك رائجًا.
أنشئ اشتراكًا في Cloud Pub/Sub لإعلام Cloud Pub/Sub بطريقة إرسال إشعاراتك.
أخيرًا، قبل التسجيل في خدمة الإشعارات الفورية، يجب منح حساب خدمة الإشعارات الفورية (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 للمورد المناسب. بالنسبة إلى الإشعارات حول التغييرات في القائمة، سيتم ملء الحقلين 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() لإلغاء التسجيل من الإشعارات.