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

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

إنشاء مرفق

أنشئ مرفقًا من خلال إرسال طلب 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 لاسترداد معلومات حول مهمة أرسلها طالب أو تعديلها.

ملاحظة مهمة: عند تقديم طلبات PATCH، لا تنسَ تقديم updateMask أيضًا. يجب أن تكون قيمة updateMask قائمة بأسماء الحقول المراد تعديلها مفصولة بفواصل.

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

أرسِل طلب 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.

تحذير: لا يتم تعديل الدرجات في الوقت الفعلي في واجهة مستخدم Google Classroom. قد يحدث تأخير يصل إلى 30 ثانية بين استلام العلامة بنجاح وعرضها في 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. ننصحك بالتحقّق من هذه القيمة وتعديلها إذا لزم الأمر في حال كان منتجك يتيح للمعلّمين تعديل نتيجة الطالب في نشاط معيّن.