التفاعل مع المرفقات

تناقش هذه الصفحة تفاصيل التنفيذ لإنشاء مرفق والتعامل مع المهام المرسَلة من الطلاب. يُرجى العِلم أنّك قد تحتاج إلى تقديم معلَمات متعلّقة بالمرفقات عند إجراء هذه الطلبات.

إنشاء مرفق

أنشئ مرفقًا من خلال إرسال طلب CREATE إلى نقطة نهاية courses.*.addOnAttachments.create المناسبة. يجب أن يتضمّن طلبك مثالاً على AddOnAttachment في نص الطلب.

يجب إدراج الحقول التالية عند إنشاء مرفق:

• title: اسم سلسلة المرفق
• teacherViewUri: معرّف الموارد المنتظم (URI) لعرض المعلّم للمرفق
• studentViewUri: معرّف الموارد المنتظم (URI) لعرض "طريقة عرض الطالب" للمرفق.
• ‫studentWorkReviewUri: عنوان URL الذي يمكن للمعلّم من خلاله الاطّلاع على عمل الطالب في المرفق هذا الحقل مطلوب فقط للمرفقات من النوع "نشاط".

قد تحتاج إلى تضمين بعض الحقول الاختيارية التالية:

• dueDate وdueTime في حال تحديد تاريخ استحقاق المرفق
• ‫maxPoints: الحد الأقصى لدرجة المرفق يجب أن تكون قيمة غير صفرية إذا كنت تريد السماح بإعادة إرسال الدرجات. ينطبق على المرفقات من النوع "نشاط" فقط.

اطّلِع على مرجع موارد "AddOnAttachment" للحصول على مزيد من التفاصيل حول هذه الحقول.

تفاصيل العينة التي أرسلها الطالب

يتّبع سير عمل الإرسال النموذجي الخطوات التالية:

1. يشغِّل الطالب studentViewUri لإكمال نشاط.
2. تستردّ الإضافة submissionId من طريقة getAddOnContext باستخدام بيانات اعتماد الطالب.
3. يخزِّن مطوّر الإضافةsubmissionId وattachmentId بصفته المعرّف الفريد لعمل الطالب. في حال نسخ المعلّم مهمة دراسية في Classroom، يمكنك استخدام المفتاح المركب لهذه المَعلمتَين لعرض مرفق جديد في المهمة الدراسية المنسوخة. يمكنك الاطّلاع على صفحتنا حول المحتوى المنسوخ للحصول على مزيد من التفاصيل.
4. يطلق المعلّم المهتم بمراجعة أعمال الطلاب studentWorkReviewUri. يتضمّن الطلب مَعلمات طلب البحث التالية: courseId وitemId وitemType وattachmentId وsubmissionId.
5. يستخدم مطوّر الإضافة المعرّفات الأربعة هذه لاسترداد عمل الطالب. استخدِم نقطة نهاية courses.courseWork.addOnAttachments.studentSubmissions ل retrieving or modifying information about a student submission.

رصد حالة الإرسال

أرسِل طلب GET إلى نقطة نهاية courses.courseWork.addOnAttachments.studentSubmissions للحصول على تفاصيل عن submissionId محدّد. تتلقّى عنصرًا من نوع AddOnAttachmentStudentSubmission يحتوي على درجة العينة التي تم إرسالها (pointsEarned) وحالتها الحالية (postSubmissionState). يمكن أن تكون حالة العينة التي تم إرسالها إحدى القيم التالية:

• NEW، إذا لم يسبق للطالب الوصول إلى المهمة الدراسية
• CREATED، إذا أنشأ الطالب إرسالًا ولكن لم يرسله بعد
• TURNED_IN، إذا أرسل الطالب عمله إلى المعلّم.
• RETURNED، إذا أرجع المعلّم المهمة إلى الطالب.
• RECLAIMED_BY_STUDENT، إذا أزال الطالب عمله.

استخدِم نقطة النهاية هذه لرصد حالة عمل الطالب في الإضافة. يمكنك بعد ذلك تعديل طرق العرض أو الخيارات المقدَّمة للطالب استنادًا إلى الحالة المعروضة. وقد تشمل هذه الميزات ما يلي:

• عرض حالة إرسال الواجبات ضمن الإضافة وقد يساعد ذلك الطلاب في تجنُّب أي التباس محتمل والتأكّد من عدم عدم إرسالهم مهمة عن طريق الخطأ.
• تقييد امتيازات تعديل العينة المرسَلة إذا كانت حالة المهمة هي CREATED أو RECLAIMED_BY_STUDENT، قد يُسمَح للطالب بتعديل المهام الدراسية. إذا كانت حالة المهمة الدراسية هي TURNED_IN أو RETURNED، قد لا يُسمح للطالب بتعديل ما أرسله.

الدرجات والمرفقات المتعددة

يمكن استخدام مرفق إضافة واحد فقط لضبط الدرجة لمهمة واحدة. إذا أنشأ المعلّم أكثر من مرفق واحد من نوع نشاط يقدّم قيمة maxPoints، لا يمكن إلا للمرفق الأول من هذا النوع ضبط درجة الواجب الدراسي. اترك قيمة maxPoints غير محدّدة أو اضبطها على صفر لمحاولة إيقاف إعادة إرسال الدرجات لمرفق.

تحديد درجة المحتوى الذي أرسلته

يمكنك تعديل نموذج أرسله أحد الطلاب من خلال إرسال طلب PATCH إلى نقطة نهاية courses.courseWork.addOnAttachments.studentSubmissions. يجب أن يتضمّن نص الطلب مثيلًا من AddOnAttachmentStudentSubmission مع القيم المعدَّلة. اضبط الحقل pointsEarned لتعديل درجة العينة التي تم إرسالها. تصبح القيمة التي تم تمريرها في pointsEarned درجة مسودة مرئية للمُعلّم في واجهة مستخدم Classroom. يمكن للمعلّمين تعديل مسودة الدرجة قبل إرجاع المهمة إلى الطلاب. اطّلِع على نظرة عامة على وضع الدرجات في واجهة مستخدم Classroom لمعرفة تفاصيل عن كيفية عرض الدرجات على المعلّمين.

تجدر الإشارة إلى أنّه لا يمكنك ضبط الدرجة باستخدام pointsEarned إلا إذا كانت الشروط التالية صحيحة:

• يجب أن يكون للمرفق قيمة موجبة maxPoints.
• يجب أن تكون الإضافة هي صانع المرفق الأصلي.

تجدُر الإشارة أيضًا إلى أنّه يمكنك تعديل قيمة maxPoints في AddOnAttachment تم إنشاؤها مسبقًا من خلال إصدار طلب PATCH إلى نقطة النهاية addOnAttachments.

حالات تحديد درجة

يمكنك تحديد وقت إعادة إرسال الدرجات إلى Google Classroom. ويتمثل الاختلاف العميق في ما إذا كنت تريد تخزين بيانات اعتماد المعلّم، لأنّه هو وحده من يمكنه تعديل الدرجات.

هناك لحظتان إضافيتان يمكنك فيهما اجتياز إحدى الدرجات إلى Google Classroom: عندما يُكمل الطالب عمله أو عندما يفتح المعلّم عمل الطالب في إطار iframe لمراجعة عمل الطلاب.

إذا كنت تريد ضبط الدرجات عندما يكمل الطالب العمل، عليك تخزين بيانات اعتماد المعلّم بلا إنترنت، ثم استردادها واستخدامها لتعديل الدرجة عندما يكمل الطالب العمل. توفّر هذه الطريقة بعض المزايا المحتملة:

• تقديم تحديثات سلسة بشأن الدرجات. لا يحتاج المعلمون إلى اتخاذ أي إجراء خاص للتسبب في تعبئة الدرجات في واجهة مستخدم Classroom.
• تقديم إحصاءات في الوقت الفعلي عن مستوى تقدّم الصف في مهمة معيّنة من خلال منح الدرجات عندما يكمل الطلاب المرفقات، يمكن للمعلّمين معرفة مستوى فهم الطلاب بدون فتح كلّ ملف تم إرساله.

يُرجى العلم أنّ هذا الأسلوب يسمح أيضًا باستخدام أسلوب غير متزامن لمزامنة الدرجات. يمكنك إجراء استطلاع دوري لنقطة نهاية AddOnAttachmentStudentSubmission لرصد الحالات التي يرسل فيها الطالب عمله. بعد إرسال العينة، اضبط درجة العينة باستخدام بيانات الاعتماد المخزّنة.

إذا كنت لا تريد تحميل بيانات اعتماد المعلّم أثناء جلسة طالب، يمكنك استخدام بيانات اعتماد المعلّم النشط عند تحميله لملف تم إرساله من قِبل الطالب في إطار iframe لمراجعة أعمال الطلاب. ومع ذلك، قد لا يوفر ذلك تجربة مستخدم سلسة نظرًا لأن الدرجات في واجهة مستخدم Classroom لا يتم تحديثها في الوقت الفعلي وسيُطلب من المعلمين فتح إطار iframe لمراجعة عمل الطلاب في كل عملية إرسال.

رصد التغييرات في درجات المهام الدراسية

يمكن للمعلمين تعديل إعدادات الدرجات في Classroom بعد إنشاء المهمة. قد تشمل هذه التعديلات ما يلي:

• تغيير قيمة النقاط المحدّدة
• تغيير قيمة maxPoints للمهمة
• تغيير ما إذا كان يجب تقييم المهمة الدراسية على الإطلاق

للاطّلاع على الإعدادات الحالية لوضع الدرجات لإحدى المهام، ننصحك بإرسال طلب GET إلى نقطة نهاية courses.courseWork. يتضمّن الردّ قيمة maxPoints الحالية. تحتوي المهمة التي لا تتضمن درجات على قيمة maxPoints فارغة أو صفر.

إذا أرسلت درجة إلى Classroom، استخدِم نقطة نهاية courses.courseWork.addOnAttachments.studentSubmissions لطلب الدرجة أو تغييرها لمرفق إضافة. يتم ضبط قيمة الدرجة باستخدام حقل pointsEarned. ننصحك بالتحقق من هذه القيمة وتعديلها إذا لزم الأمر إذا كان منتجك يسمح للمعلّمين بتعديل درجة الطالب لنشاط معيّن.