Interagir avec les pièces jointes

Cette page aborde les détails d'implémentation pour créer une pièce jointe, les actions recommandées lorsque les utilisateurs ouvrent des pièces jointes et l'utilisation des devoirs rendus par les élèves. Notez que vous devrez peut-être fournir des paramètres liés aux pièces jointes lorsque vous effectuez ces requêtes.

Créer une pièce jointe

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 la pièce jointe sous forme de chaîne.
• 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 consulter 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 et dueTime si vous spécifiez la date limite de la pièce jointe.
• maxPoints : note maximale pour la pièce jointe. Doit être une valeur différente de zéro si vous souhaitez prendre en charge le renvoi des 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 iFrames Vue élève, Vérification du travail de l'élève et Vue enseignant iFrame sont tous destinés à présenter du contenu à l'utilisateur plutôt qu'à modifier un devoir Classroom. Envisagez de procéder comme suit lorsque l'une de ces vues s'ouvre :

• Obtenez les identifiants OAuth de l'utilisateur.
• Effectuez une requête courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext ou announcements.getAddOnContext en fonction de itemType pour valider le rôle de l'utilisateur.
• Inspectez la réponse pour voir si TeacherContext ou StudentContext sont 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 itemType est courseWork, enregistrez le submissionId de la réponse avec le travail de l'élève. Les submissionIds correspondent dans les iFrames de module complémentaire et sont nécessaires pour renvoyer les notes et afficher le travail des élèves aux enseignants dans l'outil de notation.
• Si le attachmentId est déjà connu du module complémentaire, affichez l'interface utilisateur de pièce jointe appropriée.
• Sinon, cette pièce jointe doit avoir été copiée à partir d'un autre élément de flux ou cours. Pour obtenir des recommandations concernant ce scénario, consultez le guide Gérer le contenu copié.

Détails des devoirs rendus par les élèves

Un workflow de devoir rendu type suit les étapes suivantes :

1. Un élève lance le studentViewUri pour effectuer une activité.
2. Le module complémentaire récupère un submissionId à partir de la méthode getAddOnContext à l'aide des identifiants de l'élève.
3. Le développeur du module complémentaire stocke le submissionId et le attachmentId comme 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 notre page sur le contenu copié pour plus de détails.
4. Un enseignant souhaitant examiner le travail d'un élève lance le studentWorkReviewUri. La requête inclut les paramètres de requête suivants : courseId, itemId, itemType, attachmentId et submissionId.
5. Le développeur du module complémentaire utilise ces quatre ID pour récupérer le travail de l'élève. Utilisez le courses.courseWork.addOnAttachments.studentSubmissions point de terminaison pour récupérer ou modifier des informations sur un devoir rendu par un élève.

Détecter l'état de l'envoi

Émettez une GET requête au courses.courseWork.addOnAttachments.studentSubmissions point de terminaison pour obtenir des informations sur un submissionId spécifique. Vous recevez un objet AddOnAttachmentStudentSubmission, qui contient la note du devoir (pointsEarned) et son état actuel (postSubmissionState). L'état de l'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éé un devoir, mais ne l'a pas encore rendu.
• TURNED_IN, si l'élève a rendu son travail à l'enseignant.
• RETURNED, si l'enseignant a rendu le devoir à l'élève.
• RECLAIMED_BY_STUDENT, si l'élève a "annulé l'envoi" de son travail.

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 qu'ils ne manquent pas de rendre un devoir par erreur.
• Limiter les droits de modification des devoirs. Si le devoir a l'état CREATED ou RECLAIMED_BY_STUDENT, l'élève peut être autorisé à modifier son devoir. Si le devoir a l'état TURNED_IN ou RETURNED, l'élève peut ne pas être autorisé à modifier son devoir.

Notes et plusieurs pièces jointes

Une seule pièce jointe de module complémentaire peut être utilisée pour définir la note d'un devoir unique. 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. Laissez la valeur maxPoints non définie ou définissez-la sur zéro pour désactiver le renvoi des notes pour une pièce jointe.

Définir la note d'un devoir

Vous pouvez modifier un devoir rendu par 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 visible par l'enseignant dans l'interface utilisateur 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 la section 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 pièce jointe doit avoir une valeur maxPoints positive.
• Le module complémentaire doit être le créateur d'origine 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 avez le choix du moment où 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 de module complémentaire 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 Vérification du travail de l'élève.

Si vous souhaitez définir des notes lorsque l'élève termine son travail, 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 termine son travail. Cette méthode présente plusieurs avantages potentiels :

• Fournir des mises à jour de notes transparentes. Les enseignants n'ont aucune action spéciale à effectuer pour que les notes soient renseignées dans l'interface utilisateur Classroom.
• Fournir des informations en temps réel sur la progression d'une classe dans un devoir. En définissant des notes lorsque les élèves terminent les pièces jointes, les enseignants peuvent se faire une idée de la compréhension de leurs élèves sans ouvrir chaque devoir.

Notez que cette approche permet également une approche asynchrone de 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 rendu, définissez sa note à 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 Vérification du travail de l'élève. Toutefois, cela peut ne pas offrir une expérience utilisateur particulièrement fluide, car les notes de l'interface utilisateur Classroom ne sont pas mises à jour en temps réel et les enseignants devraient ouvrir l'iFrame Vérification du travail de l'élève de chaque devoir.

Détecter les modifications des 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 les éléments suivants :

• Modifier la valeur des points attribués.
• Modifier 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 GET requête au point de terminaison courses.courseWork. La réponse inclut la valeur maxPoints actuelle. Un devoir non noté 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. Envisagez de vérifier et, si nécessaire, de mettre à jour cette valeur si votre produit permet aux enseignants de modifier la note d'un élève pour une activité particulière.