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

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

إنشاء مرفق

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

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

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

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

• 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 لاسترجاع المعلومات المتعلقة بالعينة التي تم إرسالها أو تعديلها.

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