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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

إنشاء مرفق

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

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

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

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

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