Cette page aborde les détails de l'implémentation pour la création d'une pièce jointe, les actions recommandées lorsque les utilisateurs ouvrent des pièces jointes et l'utilisation des devoirs des élèves. Notez que vous devrez peut-être fournir des paramètres liés aux pièces jointes lorsque vous effectuerez ces demandes.
Créer un rattachement
Créez une pièce jointe 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 lors de la création d'une pièce jointe :
title: nom de chaîne de la pièce jointe.teacherViewUri: URI de la vue de l'enseignant de la pièce jointe.studentViewUri: URI de la vue de l'élève de la pièce jointe.studentWorkReviewUri: URI permettant à l'enseignant de voir le travail de l'élève dans la pièce jointe. Ce champ n'est requis que pour les pièces jointes de type activité.
Vous pouvez inclure certains des champs facultatifs suivants :
dueDateetdueTimesi vous spécifiez la date limite de l'attachement.maxPoints: note maximale pour le fichier joint. Doit être une valeur non nulle si vous souhaitez prendre en charge le renvoi de notes. Ne s'applique qu'aux pièces jointes de type activité.
Pour en savoir plus sur ces champs, consultez la documentation de référence sur la ressource AddOnAttachment.
Valider les identifiants et le rôle de l'utilisateur
Les iFrame de la vue de l'élève, de la vue de l'enseignant et de la vérification des devoirs des élèves sont tous destinés à présenter du contenu à l'utilisateur plutôt qu'à modifier un devoir Classroom. Lorsque l'une de ces vues s'ouvre, vous pouvez effectuer les actions suivantes :
- Obtenez les identifiants OAuth de l'utilisateur.
- Envoyez une requête
courseWork.getAddOnContext,courseWorkMaterials.getAddOnContextouannouncements.getAddOnContexten fonction deitemTypepour valider le rôle de l'utilisateur. - Inspectez la réponse pour voir si
TeacherContextouStudentContextsont présents. Un seul peut être renvoyé, correspondant au rôle de l'utilisateur dans le cours. - Si l'utilisateur actuel est un élève et que
itemTypeest défini surcourseWork, enregistrezsubmissionIdà partir de la réponse avec le travail de l'élève. La correspondancesubmissionIdsdans les iFrames de modules complémentaires est requise pour renvoyer les notes et afficher les devoirs des élèves aux enseignants dans l'outil de notation. - Si le
attachmentIdest déjà connu du module complémentaire, affichez l'UI de pièce jointe appropriée. - Sinon, cette pièce jointe doit avoir été copiée à partir d'un autre élément du flux ou d'un autre cours. Consultez le guide Gérer le contenu copié pour obtenir des recommandations sur ce scénario.
Détails des devoirs rendus par les élèves
Un workflow d'envoi type comprend les étapes suivantes :
- Un élève lance
studentViewUripour effectuer une activité. - Le module complémentaire récupère un
submissionIdà partir de la méthodegetAddOnContextà l'aide des identifiants de l'élève. submissionIdetattachmentIdsont 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é.- Un enseignant qui souhaite corriger les devoirs des élèves lance l'
studentWorkReviewUri. La requête inclut les paramètres de requête suivants :courseId,itemId,itemType,attachmentIdetsubmissionId. - Le développeur du module complémentaire utilise ces quatre ID pour récupérer le devoir de l'élève. Utilisez le point de terminaison
courses.courseWork.addOnAttachments.studentSubmissionspour récupérer ou modifier des informations sur un devoir d'élève.
Détecter l'état de l'envoi
Envoyez une requête GET au point de terminaison courses.courseWork.addOnAttachments.studentSubmissions pour obtenir des informations sur un submissionId spécifique. Vous recevez un objet AddOnAttachmentStudentSubmission, qui contient la note de la soumission (pointsEarned) et son état actuel (postSubmissionState). L'état de la soumission 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éé un devoir, mais ne l'a pas encore envoyé.TURNED_IN, si l'élève a remis son devoir à l'enseignant.RETURNED, si l'enseignant a rendu le devoir à l'élève.RECLAIMED_BY_STUDENT, si l'élève n'a pas envoyé 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 à s'assurer de ne pas oublier de rendre un devoir.
- Limiter les droits de modification des devoirs. Si le devoir est à l'état
CREATEDouRECLAIMED_BY_STUDENT, l'élève peut être autorisé à modifier son devoir. Si le devoir est à l'étatTURNED_INouRETURNED, il est possible que l'élève ne soit pas autorisé à modifier son devoir.
Notes et pièces jointes multiples
Vous ne pouvez utiliser qu'une seule pièce jointe de module complémentaire pour définir 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 de ce type peut définir la note du devoir. Pour désactiver le renvoi des notes pour une pièce jointe, laissez la valeur maxPoints non définie ou définissez-la sur zéro.
Attribuer une note à un devoir
Vous pouvez modifier un devoir d'é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 provisoire visible par l'enseignant dans l'interface utilisateur de Classroom. Les enseignants peuvent modifier la note provisoire 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 Classroom.
Notez que vous ne pouvez définir la note avec pointsEarned que si les conditions suivantes sont remplies :
- La valeur
maxPointsde la pièce jointe doit être positive. - Le module complémentaire doit être 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 pouvez choisir quand une note est renvoyée à 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 moments où vous pouvez transmettre une note à Google Classroom : lorsque l'élève termine son travail ou lorsque l'enseignant ouvre le travail de l'élève dans l'iFrame "Examen des devoirs des élèves".
Si vous souhaitez attribuer des notes lorsque l'élève a terminé le devoir, vous devez stocker les identifiants hors connexion d'un enseignant, puis les récupérer et les utiliser pour modifier la note lorsque l'élève a terminé le devoir. Cette méthode présente plusieurs avantages potentiels :
- Fournir des mises à jour de notes fluides. Les enseignants n'ont aucune action spécifique à effectuer 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 dans un devoir ; En attribuant des notes aux élèves à mesure qu'ils terminent les pièces jointes, les enseignants peuvent évaluer leur compréhension 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 remis son travail. Une fois la tâche envoyée, définissez la note de l'envoi à l'aide des identifiants stockés.
Si vous ne souhaitez pas charger les identifiants de l'enseignant lors d'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 d'examen des devoirs des élèves. Toutefois, cela ne permet pas d'offrir une expérience utilisateur 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 "Examen des travaux des élèves" pour chaque devoir.
Détecter les modifications apportées aux notes des devoirs
Les enseignants peuvent modifier les paramètres de notation dans Classroom après la création d'un devoir. Voici quelques exemples de modifications :
- Modifier le barème de notation
- Modifier la valeur
maxPointsd'un devoir. - Modifier l'état de la note de la tâche.
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 sans note a une valeur maxPoints nulle ou égale à zéro.
Si vous avez renvoyé 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. Pensez à vérifier et, si nécessaire, à mettre à jour cette valeur si votre produit permet aux enseignants de modifier la note d'un élève pour une activité spécifique.