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

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

إنشاء مرفق

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

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

• ‫title: اسم السلسلة للمرفق.
• teacherViewUri: معرّف الموارد المنتظم (URI) لعرض المرفق من قِبل المعلّم
• ‫studentViewUri: معرّف الموارد المنتظم (URI) لطريقة عرض المرفق للطلاب
• ‫studentWorkReviewUri: معرّف الموارد الموحّد (URI) الذي يتيح للمعلم الاطّلاع على عمل الطالب في المرفق. هذا الحقل مطلوب فقط للمرفقات من النوع activity-type.

يمكنك تضمين بعض الحقول الاختيارية التالية:

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

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

التحقّق من صحة بيانات اعتماد المستخدم ودوره

إنّ إطار iframe الخاص بعرض الطالب وإطار iframe الخاص بمراجعة عمل الطالب وإطار iframe الخاص بعرض المعلّم مصمّمة لعرض المحتوى للمستخدم بدلاً من تعديل مهمة في Classroom. ننصحك باتّباع الخطوات التالية عند فتح إحدى طرق العرض هذه:

• احصل على بيانات اعتماد OAuth للمستخدم.
• إجراء طلب courseWork.getAddOnContext أو courseWorkMaterials.getAddOnContext أو announcements.getAddOnContext استنادًا إلى itemType للتحقّق من صحة دور المستخدم
• افحص الردّ لمعرفة ما إذا كان يتضمّن TeacherContext أو StudentContext. يمكن عرض نتيجة واحدة فقط، وهي تتوافق مع دور المستخدم في الدورة التدريبية.
• إذا كان المستخدم الحالي طالبًا وكانت قيمة itemType هي courseWork، سجِّل submissionId من الرد مع عمل الطالب. يجب أن تتطابق submissionIds في جميع إطارات iframe الخاصة بالإضافات، وهي مطلوبة لإعادة الدرجات ولعرض أعمال الطلاب على المعلّمين في أداة وضع الدرجات.
• إذا كان attachmentId معروفًا للإضافة، اعرض واجهة مستخدم المرفق المناسبة.
• بخلاف ذلك، يجب أن يكون هذا المرفق قد تم نسخه من عنصر آخر في ساحة المشاركة أو من دورة تدريبية أخرى. راجِع دليل التعامل مع المحتوى المنسوخ للحصول على اقتراحات بشأن هذه الحالة.

تفاصيل مهمة الطالب المُرسَلة

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

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

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

أرسِل طلب 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 موجبة.
• يجب أن تكون الإضافة هي الصانع الأصلي للمرفق.

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

الوقت المناسب لتحديد درجة

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

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

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

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

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

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

رصد التغييرات في درجات الواجبات

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

• تغيير قيمة النقاط المخصّصة
• تغيير قيمة maxPoints لواجب
• تغيير ما إذا كان يجب تقييم المهمة أم لا

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

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