Interagir avec les pièces jointes

Cette page explique en détail comment créer une pièce jointe et gérer 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 une pièce jointe:

• 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 liées au type d'activité.

Vous pouvez inclure certains des champs facultatifs suivants:

• dueDate et dueTime si vous spécifiez la date d'échéance de la pièce jointe.
• maxPoints: note maximale de la pièce jointe. Cette valeur doit être différente de zéro si vous souhaitez accepter le renvoi de notes. S'applique uniquement aux pièces jointes de type activité.

Pour en savoir plus sur ces champs, consultez la documentation de référence de la ressource AddOnAttachment.

Détails de l'envoi de l'élève

Voici la procédure standard à suivre:

1. Un élève lance studentViewUri pour terminer une activité.
2. Le module complémentaire récupère un submissionId à partir de la méthode getAddOnContext à l'aide des identifiants d'étudiant.
3. Les éléments submissionId et attachmentId sont stockés par le développeur du module complémentaire en tant qu'identifiant unique du devoir 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 notre page sur le contenu copié.
4. Un enseignant qui souhaite corriger les devoirs de ses élèves lance studentWorkReviewUri. La requête inclut les paramètres de requête suivants : courseId, itemId, itemType, attachmentId et submissionId.
5. Le développeur de modules complémentaires utilise ces quatre ID pour récupérer les devoirs des élèves. Utilisez le point de terminaison courses.courseWork.addOnAttachments.studentSubmissions pour récupérer ou modifier les informations sur le travail d'un élève.

Important :Lorsque vous émettez des requêtes PATCH, n'oubliez pas de spécifier également updateMask. La valeur updateMask doit être une liste des noms de champs à modifier, séparés par une virgule.

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 (postSubmissionState). L'état de l'envoi peut correspondre à l'une des valeurs suivantes:

• NEW, si l'élève n'a jamais accédé au devoir
• CREATED, si l'élève a créé un devoir, mais ne l'a pas encore envoyé
• TURNED_IN, si l'élève a envoyé son devoir à l'enseignant
• RETURNED, si l'enseignant a rendu le devoir à l'élève
• RECLAIMED_BY_STUDENT, si l'élève a "annulé la remise" 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 fournies à l'élève 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 toute confusion par erreur.
• Limiter les droits de modification des devoirs Si le devoir est associé à l'état CREATED ou RECLAIMED_BY_STUDENT, l'élève peut être autorisé à modifier son travail. Si le devoir est associé à l'état TURNED_IN ou RETURNED, il est possible que l'élève ne soit pas autorisé à modifier son travail.

Notes et plusieurs pièces jointes

Important :Pensez à permettre aux enseignants d'activer ou de désactiver le renvoi des notes lorsqu'ils créent une pièce jointe.

Vous ne pouvez attribuer la note qu'à un seul devoir en pièce jointe de module complémentaire. Si un enseignant crée plusieurs pièces jointes de type d'activité fournissant une valeur maxPoints, seule la première pièce jointe peut définir la note du devoir. Ne définissez pas la valeur maxPoints 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 envoi

Vous pouvez modifier l'envoi 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 devoir. La valeur transmise dans pointsEarned devient une note temporaire que l'enseignant peut voir dans l'interface utilisateur de Classroom. Les enseignants peuvent modifier la note temporaire avant de rendre le devoir aux élèves. Pour en savoir plus sur la façon dont les notes sont présentées aux enseignants, consultez Présentation de la notation dans l'interface utilisateur de Classroom.

Avertissement :Les notes ne sont pas mises à jour dans l'interface utilisateur de Google Classroom en temps réel. Un délai de 30 secondes peut s'écouler entre la réception d'une note et son affichage dans Classroom.

Notez que vous ne pouvez définir la note avec pointsEarned que si les conditions suivantes sont remplies:

• La pièce jointe doit avoir une valeur maxPoints positive.
• Il doit s'agir du 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 définir une note ?

Vous pouvez décider du moment où la note sera renvoyée dans Google Classroom. La distinction essentielle est de savoir si vous choisissez de stocker les identifiants de l'enseignant, car seul l'enseignant peut modifier une note.

Il existe deux modules complémentaires au cours desquels vous pouvez attribuer une note à Google Classroom: lorsque l'élève termine son travail ou lorsque l'enseignant ouvre son devoir dans l'iFrame de l'examen de son devoir.

Si vous souhaitez définir des notes 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 lorsque l'élève a terminé le travail. Cette méthode présente certains avantages potentiels:

• Mettre à jour facilement les notes. Aucune action spéciale n'est requise pour que les notes s'affichent dans l'interface utilisateur de Classroom.
• fournir des informations en temps réel sur la progression d'une classe tout au long d'un devoir ; En définissant une note lorsque les élèves remplissent les pièces jointes, les enseignants peuvent se faire une idée de ce qu'ils ont compris 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 envoyé son travail. Une fois l'envoi 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 lorsqu'il charge le devoir de l'élève dans l'iFrame de l'examen des devoirs des élèves. Toutefois, l'expérience utilisateur n'est pas particulièrement fluide, car les notes dans l'interface utilisateur Classroom ne sont pas mises à jour en temps réel, et les enseignants doivent ouvrir l'iFrame de l'évaluation des devoirs des élèves pour chaque devoir.

Détecter les changements de notes dans les devoirs

Important :Pensez à vérifier les paramètres de notation actuels d'un devoir avant de définir la note d'un envoi.

les enseignants peuvent modifier les paramètres de notes dans Classroom après avoir créé un devoir. Ces modifications peuvent inclure les éléments suivants:

• Modification du barème de notation attribué.
• Modifier la valeur maxPoints d'un devoir
• Changer si le devoir doit être noté du tout.

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 retransmis une note à Classroom, utilisez le point de terminaison courses.courseWork.addOnAttachments.studentSubmissions pour récupérer ou modifier la note d'une pièce jointe de module complémentaire. La valeur de la note est définie à l'aide du champ pointsEarned. Envisagez de vérifier et, si nécessaire, de modifier cette valeur si votre produit permet aux enseignants de modifier le score d'un élève pour une activité particulière.