Interagir avec les pièces jointes

Cette page présente les détails d'implémentation pour créer une pièce jointe et travailler avec 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 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 chaîne de l'attachement.
• teacherViewUri: URI de la vue 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 sur le rattachement. 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 indiquez la date d'échéance de la pièce jointe.
• maxPoints: note maximale pour la pièce jointe. Doit être une valeur non nulle si vous souhaitez accepter le transfert 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.

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

Un workflow d'envoi type suit les étapes suivantes:

1. Un élève lance 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. Les submissionId et attachmentId 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 notre page sur le contenu copié.
4. Un enseignant qui souhaite corriger les devoirs des é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 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 des informations sur un devoir d'élève.

Important :Lorsque vous envoyez des requêtes PATCH, n'oubliez pas de fournir également le 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 informations sur un submissionId spécifique. Vous recevez un objet AddOnAttachmentStudentSubmission, qui contient la note (pointsEarned) et l'état actuel (postSubmissionState) de l'envoi. 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 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 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 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 s'oublient pas de rendre un devoir.
• Limiter les droits de modification des envois Si le devoir affiche l'état CREATED ou RECLAIMED_BY_STUDENT, l'élève peut être autorisé à modifier son devoir. Si l'état du devoir est TURNED_IN ou RETURNED, l'élève n'est peut-être pas autorisé à modifier son devoir.

Notes et pièces jointes multiples

Point clé :Envisagez de permettre aux enseignants d'activer ou de désactiver la transmission des notes lorsqu'ils créent une pièce jointe.

Vous ne pouvez utiliser qu'une seule pièce jointe de module complémentaire pour définir la note d'un seul 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 de l'exercice. Laissez la valeur maxPoints non définie ou définissez-la sur zéro pour désactiver le transfert de note pour une pièce jointe.

Définir la note d'un devoir

Vous pouvez modifier le devoir 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 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 de Classroom.

Avertissement :Les notes ne sont pas mises à jour en temps réel dans l'interface utilisateur de Google Classroom. Il peut s'écouler jusqu'à 30 secondes 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.
• 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 pouvez choisir quand une note est transmise à 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 son travail dans l'iframe "Examen du travail des élèves".

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

• Fournir des mises à jour de notes fluides Les enseignants n'ont pas besoin d'effectuer d'action particulière pour que les notes s'affichent dans l'interface utilisateur de Classroom.
• Obtenez des insights en temps réel sur la progression d'une classe dans un devoir. En attribuant des notes aux élèves à mesure qu'ils remplissent les pièces jointes, les enseignants peuvent évaluer leur compréhension sans ouvrir chaque devoir.

Notez que cette approche permet également d'utiliser une approche asynchrone pour la synchronisation des notes. Vous pouvez interroger périodiquement le point de terminaison AddOnAttachmentStudentSubmission pour détecter quand un élève a rendu son travail. Une fois le devoir envoyé, définissez la note à l'aide des identifiants stockés.

Si vous ne souhaitez pas charger les identifiants de l'enseignant pendant une session d'élève, vous pouvez utiliser les identifiants de l'enseignant actif lorsqu'il charge le devoir de l'élève dans l'iframe d'évaluation des devoirs des élèves. Toutefois, cela n'offre pas toujours une expérience utilisateur particulièrement fluide, car les notes dans l'interface utilisateur de Classroom ne sont pas mises à jour en temps réel et les enseignants doivent ouvrir l'iframe d'évaluation des devoirs des élèves pour chaque devoir.

Détecter les modifications des notes de devoirs

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

Les enseignants peuvent modifier les paramètres de notation dans Classroom après avoir créé un devoir. Ces modifications peuvent inclure les suivantes:

• Modifier la valeur des points attribués
• Modification de la valeur maxPoints d'un devoir
• Indiquer si l'évaluation de l'exercice doit être effectuée

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. Une 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 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é spécifique.