تتوافق واجهة مستخدم Classroom مع خمسة أنواع من الواجبات الدراسية: المهام الدراسية، ومهام الاختبار، والأسئلة ذات الإجابات القصيرة، والأسئلة متعددة الخيارات، والمواد. تتيح Classroom API حاليًا استخدام ثلاثة من هذه الأنواع، المعروفة باسم CourseWorkType
لواجهة برمجة التطبيقات: المهام الدراسية، والأسئلة ذات الإجابات القصيرة، والأسئلة متعددة الخيارات.
للوصول إلى هذه الوظيفة، يمكنك استخدام مورد CourseWork، الذي يمثل مهمة دراسية أو سؤالاً تم تعيينه للطلاب في دورة تدريبية معينة، بما في ذلك أي مواد وتفاصيل إضافية، مثل تاريخ الاستحقاق أو الحد الأقصى للدرجات.
بالإضافة إلى مورد CourseWork، يمكنك إدارة المهام المكتملة
باستخدام مورد StudentSubmission
. تصف الأقسام التالية هذه
بمزيد من التفصيل.
إنشاء مهام
يمكن إنشاء المهام الدراسية فقط بالنيابة عن معلِّمي الدورة التدريبية، وسيؤدي محاولة إنشاء مهام في دورة تدريبية بالنيابة عن أحد الطلاب إلى حدوث الخطأ 403 PERMISSION_DENIED
. وبالمثل، لا يمكن لمشرفي النطاق أيضًا إنشاء مهام للدورات التدريبية التي لا يعلمونها، وسيؤدي محاولة إجراء ذلك من خلال واجهة برمجة التطبيقات إلى ظهور خطأ 403 PERMISSION_DENIED
.
عند إنشاء مهام باستخدام طريقة courses.courseWork.create
، يمكنك إرفاق الروابط بتنسيق materials
، كما هو موضّح في الرمز النموذجي أدناه:
Java
Python
وتتضمن النتيجة معرِّفًا مُعيَّنًا للخادم يمكن استخدامه للإشارة إلى المهمة في طلبات واجهة برمجة التطبيقات الأخرى.
لتضمين المواد المرتبطة في مهمة تم إنشاؤها عبر Classroom API، استخدِم مرجع رابط، مع تحديد عنوان URL المستهدف. تجلب خدمة Classroom العنوان والصورة المصغّرة تلقائيًا. تتوافق واجهة برمجة التطبيقات Classroom API في الأساس مع Google Drive ومواد YouTube، والتي يمكن تضمينها مع مورد DriveFile أو مورد YouTubeVideo بطريقة مماثلة.
لتحديد تاريخ تسليم، اضبط الحقلَين dueDate
وdueTime
على
التوقيت العالمي المنسَّق (UTC) المقابل. يجب أن يكون تاريخ التسليم في المستقبل.
استرداد المهام والأسئلة
يمكنك استرداد المهام والأسئلة للطلاب والمعلمين في الدورة التدريبية المقابلة أو من قبل مشرف النطاق. لاسترداد مهمة أو سؤال معين، استخدم courses.courseWork.get. لاسترداد جميع المهام أو الأسئلة (تتطابق مع بعض المعايير اختياريًا)، استخدم courses.courseWork.list.
يعتمد النطاق المطلوب على دور المستخدم الذي قدّم الطلب في الدورة. إذا كان المستخدم طالبًا، استخدِم أحد النطاقات التالية:
https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me
إذا كان المستخدم مدرسًا أو مشرف نطاق، استخدِم أحد النطاقات التالية:
https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students
إنّ الحصول على إذن باسترداد مَهمة دراسية أو سؤال لا يعني إذنًا بالوصول إلى المواد أو البيانات الوصفية للمواد الأساسية. من الناحية العملية، يعني ذلك أن المشرف قد لا يرى عنوان ملف Drive المرفق إذا لم يكن عضوًا في الدورة التدريبية. إذا كنت تريد السماح للمشرفين بالوصول إلى ملفات المستخدم، راجع دليل التفويض على مستوى النطاق.
إدارة ردود الطلاب
يمثل مورد StudentSubmission
العمل المنجز ودرجة الطالب في مَهمة دراسية أو
سؤال. يتم إنشاء مورد StudentSubmission
بشكل ضمني لكل طالب عند إنشاء سؤال أو
مهمة جديدة.
توضّح الأقسام التالية الإجراءات الشائعة التي تدير ردود الطلاب.
استرداد إجابات الطلاب
يمكن للطلاب استرداد المهام الدراسية التابعة لهم، كما يمكن للمعلمين استرداد عمليات الإرسال
لجميع الطلاب في دوراتهم التدريبية، ويمكن لمشرفي النطاق استرداد جميع عمليات الإرسال لجميع الطلاب في نطاقهم. يتم تخصيص معرّف لكل عملية إرسال من الطالب، وإذا كنت تعرف المعرّف، يمكنك استخدام courses.courseWork.studentSubmissions.get
لاسترداده.
استخدِم طريقة courses.courseWork.studentSubmissions.list
للحصول على موارد
StudentSubmission
تتطابق مع بعض المعايير، كما هو موضّح في
العيّنة التالية:
Java
Python
يمكنك استرداد موارد StudentSubmission
التي تنتمي إلى طالب معين من خلال تحديد المعلمة userId
، كما هو موضح في النموذج التالي:
Java
Python
يتم تحديد الطلاب من خلال المعرّف الفريد أو عنوان البريد الإلكتروني الفريد للمستخدم، على النحو الذي يتم إرجاعه من خلال حزمة تطوير البرامج (SDK) لوحدة تحكُّم المشرف في Google. قد يشير المستخدم الحالي أيضًا إلى رقم تعريفه
باستخدام الاختصار "me"
.
من الممكن أيضًا الحصول على تسليمات الطلاب لجميع المهام داخل الدورة التدريبية. لإجراء ذلك، استخدِم القيمة الحرفية "-"
كقيمة courseWorkId
، كما هو موضّح في النموذج التالي:
Java
service.courses().courseWork().studentSubmissions()
.list(courseId, "-")
.set("userId", userId)
.execute();
Python
service.courses().courseWork().studentSubmissions().list(
courseId=<course ID or alias>,
courseWorkId='-',
userId=<user ID>).execute()
يعتمد النطاق المطلوب على دور المستخدم الذي قدّم الطلب في الدورة. استخدِم النطاق التالي إذا كان المستخدم معلِّمًا أو مشرفًا في نطاق:
https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students
يمكنك استخدام النطاق التالي إذا كان المستخدم طالبًا:
https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me
إنّ الحصول على إذن باسترداد أحد العناصر الدراسية لا يشير ضمنًا إلى منح الإذن بالوصول إلى المرفقات أو البيانات الوصفية للمرفقات. من الناحية العملية، يعني ذلك أن المشرف قد لا يرى عنوان ملف Drive المرفق إذا لم يكن عضوًا في الدورة التدريبية. إذا كنت تريد السماح للمشرفين بالوصول إلى ملفات المستخدم، راجِع دليل التفويض على مستوى النطاق.
إضافة مرفقات إلى ردّ الطالب
يمكنك إرفاق روابط إلى عناصر أرسلها الطالب من خلال إرفاق مورد Link
أو
DriveFile
أو YouTubeVideo
. يتم ذلك باستخدام courses.courseWork.studentSubmissions.modifyAttachments
، كما هو موضح في النموذج التالي:
Java
Python
يتم تحديد مرفق الرابط من خلال عنوان URL المستهدف، وستعمل خدمة Classroom تلقائيًا على جلب العنوان والصورة المصغّرة. يمكنك التعرف على المواد الأخرى في الصفحات المرجعية الخاصة بها.
لا يمكن تعديل StudentSubmission
إلا من قِبل معلِّم الدورة التدريبية أو الطالب الذي يملكه. لا يمكنك إرفاق Materials
إلا إذا كانت قيمة
CourseWorkType
التي أرسلها الطالب هي ASSIGNMENT
.
يعتمد النطاق المطلوب على دور المستخدم الذي قدّم الطلب في الدورة. يمكنك استخدام النطاق التالي إذا كان المستخدم مُعلّمًا:
https://www.googleapis.com/auth/classroom.coursework.students
يمكنك استخدام النطاق التالي إذا كان المستخدم طالبًا:
https://www.googleapis.com/auth/classroom.coursework.me
إدارة حالة استجابة الطالب
قد يتم إلغاء إرسال ردّ الطالب أو تسليمه أو إرجاعه. حقل الولاية في StudentSubmission
يشير إلى الحالة الحالية. لتغيير الحالة، يمكنك استدعاء
إحدى الطرق التالية:
courses.courseWork.studentSubmissions.turnIn
courses.courseWork.studentSubmissions.return
courses.courseWork.studentSubmissions.reclaim
تستغرق كل هذه الطرق نصًا فارغًا. مثال:
Java
Python
service.courses().courseWork().studentSubmission().turnIn(
courseId=<course ID or alias>,
courseWorkId=<courseWork ID>,
id=<studentSubmission ID>,
body={}).execute()
يمكن فقط للطالب الذي يملك StudentSubmission
تسليمه أو استرداده.
لا يمكن استرداد سوى المستندات التي تم تسليمها. يمكن لمعلّمي الدورة التدريبية إرجاع
StudentSubmission
فقط إذا كان في حالته السابقة.
ردود الطلاب
يتضمن المورد StudentSubmission
حقلين لتخزين الدرجات:
assignedGrade
، وهو الدرجة التي يتم إبلاغ الطلاب بها، وdraftGrade
،
وهو صف مبدئي مرئي للمعلّمين فقط. يتم تعديل هذه الحقول
باستخدام courses.courseWork.studentSubmissions.patch
مع إضافة قناع حقل
يحتوي على الحقول المناسبة، كما هو موضَّح في النموذج التالي.
Java
Python
studentSubmission = {
'assignedGrade': 99,
'draftGrade': 80
}
service.courses().courseWork().studentSubmissions().patch(
courseId=<course ID or alias>,
courseWorkId=<courseWork ID>,
id=<studentSubmission ID>,
updateMask='assignedGrade,draftGrade',
body=studentSubmission).execute()
عند العمل باستخدام واجهة مستخدم Classroom، لا يمكن للمعلمين تعيين درجة قبل حفظ الدرجة الأولية. يمكن بعد ذلك إعادة الدرجة المعينة إلى أحد الطلاب. ويجب أن تحاكي التطبيقات هذا السلوك. يمكن لتطبيقك وضع درجة على مهمة الطالب بإحدى طريقتين:
تخصيص
draftGrade
فقط. وهذا مفيد، على سبيل المثال، السماح للمعلم بمراجعة الدرجات يدويًا قبل الانتهاء منها. لا يمكن للطلاب الاطّلاع على الدرجات الأولية.يمكنك تعيين كل من
draftGrade
وassignedGrade
لوضع الدرجات على إحدى المهام الدراسية بالكامل.
إدراج الدرجات التي تم تخصيصها
يمكنك إدراج جميع الدرجات لعنصر معيّن من مهام الدورة الدراسية من خلال الاطّلاع على كائن الاستجابة لطريقة courses.courseWork.studentSubmissions.list
:
Java
Python
response = coursework.studentSubmissions().list(
courseId=course_id,
courseWorkId=coursework_id,
pageSize=10).execute()
submissions.extend(response.get('studentSubmissions', []))
if not submissions:
print('No student submissions found.')
print('Student Submissions:')
for submission in submissions:
print(f"Submitted at:"
f"{(submission.get('userId'), submission.get('assignedGrade'))}")