تدعم واجهة مستخدم Classroom خمسة أنواع من الواجبات الدراسية: المهام، والمهام الدراسية للاختبار، وأسئلة ذات إجابات قصيرة، وأسئلة الخيارات المتعدّدة، والمواد. تتيح واجهة برمجة تطبيقات Classroom حاليًا استخدام ثلاثة أنواع من هذه الأنواع، والتي تُعرف باسم CourseWorkType
لواجهة برمجة التطبيقات: "مهام" وأسئلة ذات إجابات قصيرة وأسئلة "خيارات متعدّدة".
للوصول إلى هذه الوظيفة، يمكنك استخدام مورد CourseWork الذي يمثل مهمة دراسية أو سؤال تم تعيينه للطلاب في دورة تدريبية معيّنة، بما في ذلك أي مواد وتفاصيل إضافية، مثل تاريخ التسليم أو الحد الأقصى للنتائج.
بالإضافة إلى مورد CourseWork، يمكنك إدارة المهام المكتملة باستخدام مورد StudentSubmission
. تصف الأقسام التالية هذه
بشكل أكثر تفصيلاً.
إنشاء مهام
يمكن إنشاء المهام الدراسية فقط نيابةً عن معلِّمي الدورة التدريبية، وسيؤدي محاولة إنشاء مهام دراسية في دورة تدريبية نيابةً عن الطالب إلى ظهور خطأ PERMISSION_DENIED
403. وبالمثل، لا يمكن لمشرفي النطاقات أيضًا إنشاء
مهام دراسية للدورات التعليمية التي لا يدرسون لها، كما سيؤدي إجراء ذلك من خلال واجهة برمجة التطبيقات
إلى حدوث خطأ 403 PERMISSION_DENIED
أيضًا.
عند إنشاء المهام باستخدام طريقة courses.courseWork.create
، يمكنك إرفاق الروابط بتنسيق materials
، الموضحة في نموذج الرمز أدناه:
لغة Java
لغة Python
تتضمن النتيجة معرّفًا يعيّنه الخادم يمكن استخدامه للإشارة إلى التخصيص في طلبات واجهة برمجة التطبيقات الأخرى.
لتضمين مواد مرتبطة في مهمة دراسية تم إنشاؤها من خلال Classroom API، يمكنك استخداممورد الرابط، مع تحديد عنوان URL المستهدف. يجلب تطبيق Classroom العنوان والصورة المصغّرة تلقائيًا. تتوافق أيضًا واجهة برمجة تطبيقات Classroom في الأصل مع مواد Google Drive وYouTube، والتي يمكن تضمينها مع مورد DriveFile أو مورد فيديو YouTube بطريقة مماثلة.
لتحديد تاريخ تسليم، اضبط الحقلين dueDate
وdueTime
على
التوقيت العالمي المنسّق المقابل. يجب أن يكون تاريخ التسليم في المستقبل.
استرداد المهام والأسئلة
يمكنك استرداد المهام والأسئلة للطلاب والمعلمين في الدورة التدريبية المطابقة أو عن طريق مشرف النطاق. لاسترداد مهمة دراسية أو سؤال معيّن، استخدم الدورة التدريبية.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'))}")