تتوفّر الآن إضافات Google Classroom بشكل عام للمطوّرين. يُرجى الاطّلاع على مستندات الإضافات للحصول على مزيد من المعلومات.

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

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

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

إنشاء مرفق

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

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

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

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

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

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

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

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

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

تفاصيل العمل الذي يرسله الطالب

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

يفتح الطالب studentViewUri لإكمال نشاط.
تستردّ الإضافة submissionId من طريقة getAddOnContext باستخدام بيانات اعتماد الطالب.
يخزّن مطوّر الإضافة submissionId وattachmentId كمعرّف فريد لعمل الطالب. في حال نسخ المعلّم واجبًا في Classroom، يمكنك استخدام المفتاح المركّب لهاتَين المَعلمتَين لعرض مرفق جديد في الواجب المنسوخ. راجِع صفحتنا حول المحتوى المنسوخ لمزيد من التفاصيل.
يفتح المعلّم المهتم بمراجعة عمل الطالب studentWorkReviewUri. يتضمّن الطلب مَعلمات طلب البحث التالية: courseId وitemId وitemType وattachmentId وsubmissionId.
يستخدم مطوّر الإضافة هذه المعرّفات الأربعة لاسترداد عمل الطالب. استخدِم نقطة النهاية 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 للمرفق موجبة.
يجب أن تكون الإضافة هي منشئ المرفق الأصلي.

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

الوقت المناسب لضبط درجة

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

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

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

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

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

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

اكتشاف التغييرات في درجات الواجب

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

تغيير قيمة النقاط المخصّصة
تغيير قيمة maxPoints لواجب
تغيير ما إذا كان يجب وضع درجات للواجب على الإطلاق

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

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