Cette page présente les détails d'implémentation permettant de créer une pièce jointe et de traiter les devoirs des élèves. Notez que vous devrez peut-être fournir des paramètres liés aux pièces jointes lorsque vous effectuerez ces requêtes.
Créer un rattachement
Créez un rattachement en envoyant une requête CREATE
au point de terminaison courses.*.addOnAttachments.create
approprié. Votre requête doit inclure une instance de AddOnAttachment
dans le corps de la requête.
Les champs suivants sont obligatoires lorsque vous créez un rattachement:
title
: nom de la chaîne du rattachement.teacherViewUri
: URI de la vue enseignant de la pièce jointe.studentViewUri
: URI de la vue élève de la pièce jointe.studentWorkReviewUri
: URI permettant à l'enseignant de voir le travail de l'élève sur la pièce jointe. Ce champ n'est obligatoire que pour les pièces jointes de type activité.
Vous pouvez inclure certains des champs facultatifs suivants:
dueDate
etdueTime
si vous spécifiez la date limite de remise de la pièce jointe.maxPoints
: note maximale de la pièce jointe. Cette valeur doit être non nulle si vous voulez permettre le renvoi des notes. S'applique uniquement aux rattachements de type d'activité.
Pour en savoir plus sur ces champs, consultez la documentation de référence de la ressource AddOnAttachment
.
Détails du devoir envoyé par l'élève
Voici le processus type d'envoi:
- Un élève lance l'
studentViewUri
pour terminer une activité. - Le module complémentaire récupère un
submissionId
à partir de la méthodegetAddOnContext
à l'aide des identifiants des élèves. - Les éléments
submissionId
etattachmentId
sont stockés par le développeur du module complémentaire en tant qu'identifiant unique du travail de l'élève. Si un enseignant copie un devoir dans Classroom, vous pouvez utiliser la clé composite de ces deux paramètres pour afficher une nouvelle pièce jointe dans le devoir copié. Pour en savoir plus, consultez la page sur le contenu copié. - Un enseignant qui souhaite vérifier les devoirs de ses élèves lance l'
studentWorkReviewUri
. La requête inclut les paramètres suivants :courseId
,itemId
,itemType
,attachmentId
etsubmissionId
. - Le développeur du module complémentaire utilise ces quatre ID pour récupérer le travail des élèves. Utilisez le point de terminaison
courses.courseWork.addOnAttachments.studentSubmissions
pour récupérer ou modifier les informations concernant le travail d'un élève.
Détecter l'état d'envoi
Envoyez une requête GET
au point de terminaison courses.courseWork.addOnAttachments.studentSubmissions
pour obtenir des détails sur un submissionId
spécifique. Vous recevez un objet AddOnAttachmentStudentSubmission
, qui contient la note (pointsEarned
) et l'état actuel du devoir (postSubmissionState
). L'état d'envoi peut être l'une des valeurs suivantes:
NEW
, si l'élève n'a jamais accédé au devoir.CREATED
, si l'élève a créé son devoir, mais ne l'a pas encore envoyé.TURNED_IN
, si l'élève a rendu son travail à l'enseignantRETURNED
, si l'enseignant a rendu le devoir à l'élèveRECLAIMED_BY_STUDENT
, si l'élève a annulé l'envoi de son devoir.
Utilisez ce point de terminaison pour détecter l'état du travail de l'élève dans votre module complémentaire. Vous pouvez ensuite ajuster les vues ou les options proposées à l'étudiant en fonction de l'état renvoyé. Cela peut inclure des fonctionnalités telles que:
- Afficher l'état de remise des devoirs dans votre module complémentaire. Cela peut aider les élèves à éviter toute confusion et à éviter de rendre leur devoir par erreur.
- Restriction des droits de modification de l'envoi. Si le devoir est associé à l'état
CREATED
ouRECLAIMED_BY_STUDENT
, l'élève peut être autorisé à modifier son devoir. Si l'état du devoir estTURNED_IN
ouRETURNED
, il est possible que l'élève ne soit pas autorisé à modifier son devoir.
Notes et pièces jointes multiples
Une seule pièce jointe de module complémentaire peut être utilisée pour noter la note d'un devoir. Si un enseignant crée plusieurs pièces jointes de type activité qui fournissent une valeur maxPoints
, seule la première pièce jointe peut définir la note du devoir. Laissez la valeur maxPoints
non définie ou définissez-la sur zéro afin de désactiver le renvoi des notes pour une pièce jointe.
Définir la note d'un devoir
Vous pouvez modifier le travail d'un élève en envoyant une requête PATCH
au point de terminaison courses.courseWork.addOnAttachments.studentSubmissions
. Le corps de la requête doit inclure une instance de AddOnAttachmentStudentSubmission
avec les valeurs modifiées. Définissez le champ pointsEarned
pour modifier la note d'un envoi.
La valeur transmise dans pointsEarned
devient une note temporaire visible par l'enseignant dans l'interface utilisateur de Classroom. Les enseignants peuvent modifier la note
avant de rendre le devoir aux élèves. Pour en savoir plus sur la manière dont les notes sont présentées aux enseignants, consultez la page Présentation de la notation dans l'interface utilisateur de Classroom.
Notez que vous ne pouvez définir une note avec pointsEarned
que si les conditions suivantes sont remplies:
- La pièce jointe doit comporter une valeur
maxPoints
positive. - Le module complémentaire doit avoir été le créateur initial de la pièce jointe.
Notez également que vous pouvez modifier la valeur maxPoints
d'un AddOnAttachment
déjà créé en envoyant une requête PATCH
au point de terminaison addOnAttachments
.
Quand attribuer une note ?
Vous avez la possibilité de choisir le moment où une note est renvoyée à Google Classroom. La distinction essentielle est de choisir de stocker ou non les identifiants de l'enseignant, car seul l'enseignant peut modifier une note.
Il existe deux moments complémentaires au cours desquels vous pouvez transmettre une note à Google Classroom: lorsque l'élève termine son travail ou lorsque l'enseignant ouvre le devoir de l'élève dans l'iFrame de révision des devoirs des élèves.
Si vous souhaitez définir une note lorsque l'élève a terminé son travail, vous devez stocker les identifiants hors connexion de l'enseignant, puis les récupérer et les utiliser pour modifier la note une fois que l'élève a terminé le travail. Cette méthode offre plusieurs avantages potentiels:
- Actualisez facilement les notes. Aucune action particulière n'est requise de la part des enseignants pour que les notes s'affichent dans l'interface utilisateur de Classroom.
- Fournissez des informations en temps réel sur la progression d'un cours dans le cadre d'un devoir. En définissant les notes à mesure que les élèves remplissent les pièces jointes, les enseignants peuvent se faire une idée de la compréhension de leurs élèves sans avoir à ouvrir chaque devoir.
Notez que cette approche permet également une approche asynchrone pour la synchronisation des notes. Vous pouvez interroger régulièrement le point de terminaison AddOnAttachmentStudentSubmission
pour détecter quand un élève a rendu son travail. Une fois le devoir envoyé, définissez sa note à l'aide des identifiants stockés.
Si vous ne souhaitez pas charger les identifiants de l'enseignant pendant une session élève, vous pouvez utiliser les identifiants de l'enseignant actif lors du chargement du devoir de l'élève dans l'iFrame d'évaluation des devoirs des élèves. Toutefois, cela risque de ne pas offrir une expérience utilisateur particulièrement fluide, car les notes ne sont pas mises à jour en temps réel dans l'interface utilisateur de Classroom, et les enseignants devront ouvrir l'iFrame de révision des devoirs des élèves à chaque envoi.
Détecter les changements dans les notes des devoirs
les enseignants peuvent modifier les paramètres de notation dans Classroom après la création d'un devoir. Ces modifications peuvent inclure:
- Modifier la valeur des points attribués.
- Modification de la valeur
maxPoints
d'un devoir. - Modifier si le devoir doit être noté ou non
Pour afficher les paramètres de notation actuels d'un devoir, nous vous recommandons d'envoyer une requête GET
au point de terminaison courses.courseWork
. La réponse inclut la valeur maxPoints
actuelle. Un devoir non noté a une valeur maxPoints
nulle ou nulle.
Si vous avez renvoyé une note à Classroom, utilisez le point de terminaison courses.courseWork.addOnAttachments.studentSubmissions
pour récupérer ou modifier la note associée à une pièce jointe de module complémentaire. La valeur de la note est définie à l'aide du champ pointsEarned
. Pensez à vérifier et, si nécessaire, à mettre à jour cette valeur si votre produit permet aux enseignants de modifier le score d'un élève pour une activité particulière.