L'interface utilisateur de Classroom accepte cinq types de travaux et devoirs: Devoirs, Devoirs avec quiz, Questions à réponse courte, Questions à choix multiples et Supports de cours. L'API Classroom est actuellement compatible avec trois de ces types, appelés CourseWorkType
: Devoirs, les questions à réponse courte et les questions à choix multiples.
Materials
à des ressources CourseWorkType
: devoirs, questions à réponse courte et questions à choix multiples.
Pour accéder à cette fonctionnalité, vous pouvez utiliser la ressource courseWork, qui représente un devoir ou une question attribués aux élèves d'un cours particulier, y compris tous les supports et détails supplémentaires, tels que la date limite ou le score maximal.
En plus de la ressource CourseWork, vous pouvez gérer les devoirs terminés avec la ressource StudentSubmission
. Les sections suivantes les décrivent plus en détail.
Créer des devoirs
Les devoirs peuvent être créés uniquement au nom des enseignants du cours. Si vous tentez de créer des devoirs dans un cours pour le compte d'un élève, une erreur 403 PERMISSION_DENIED
est générée. De même, les administrateurs de domaine ne peuvent pas non plus créer d'attributions pour des cours qu'ils n'enseignent pas. Toute tentative de le faire via l'API entraîne également une erreur 403 PERMISSION_DENIED
.
Lorsque vous créez des attributions à l'aide de la méthode courses.courseWork.create
, vous pouvez joindre des liens en tant que materials
, comme indiqué dans l'exemple de code ci-dessous:
Java
Python
Le résultat inclut un identifiant attribué par le serveur qui peut être utilisé pour référencer l'attribution dans d'autres requêtes API.
Pour inclure des supports de cours associés dans un devoir créé via l'API Classroom, utilisez une ressource Lien, en indiquant l'URL cible. Classroom récupère automatiquement le titre et la miniature. L'API Classroom est également compatible de manière native avec les supports Google Drive et YouTube, qui peuvent être inclus de la même manière dans une ressource DriveFile ou une ressource YouTubeVideo.
Pour spécifier une date limite, définissez les champs dueDate
et dueTime
sur l'heure UTC correspondante. La date limite doit être située dans le futur.
Récupérer les devoirs et les questions
Vous pouvez récupérer les devoirs et les questions des élèves et des enseignants du cours correspondant ou par un administrateur de domaine. Pour récupérer un devoir ou une question spécifique, utilisez courses.courseWork.get. Pour récupérer tous les devoirs ou questions (correspondant éventuellement à certains critères), utilisez courses.courseWork.list.
Le champ d'application requis dépend du rôle que possède l'utilisateur à l'origine de la demande dans le cours. Si l'utilisateur est un élève, utilisez l'un des champs d'application suivants:
https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me
Si l'utilisateur est un enseignant ou un administrateur de domaine, utilisez l'un des champs d'application suivants:
https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students
Avoir l'autorisation de récupérer un devoir ou une question n'implique pas l'autorisation d'accéder à des contenus ou à leurs métadonnées. En pratique, cela signifie qu'un administrateur peut ne pas voir le titre d'un fichier Drive joint s'il n'est pas membre du cours. Si vous souhaitez autoriser les administrateurs à accéder aux fichiers utilisateur, consultez le guide sur la délégation au niveau du domaine.
Gérer les réponses des élèves
Une ressource StudentSubmission
représente le travail effectué et la note d'un élève pour un devoir ou une question. Une ressource StudentSubmission
est créée implicitement pour chaque élève lorsqu'une question ou un devoir est créé.
Les sections suivantes expliquent les actions courantes qui permettent de gérer les réponses des élèves.
Récupérer les réponses des élèves
Les élèves peuvent récupérer leurs propres devoirs, les enseignants peuvent récupérer les devoirs de tous les élèves de leurs cours et les administrateurs de domaine peuvent récupérer tous les devoirs de tous les élèves de leur domaine. Un identifiant est attribué à chaque élève. Si vous connaissez cet identifiant, utilisez courses.courseWork.studentSubmissions.get
pour le récupérer.
Utilisez la méthode courses.courseWork.studentSubmissions.list
pour obtenir les ressources StudentSubmission
correspondant à certains critères, comme illustré dans l'exemple suivant:
Java
Python
Récupérez les ressources StudentSubmission
appartenant à un élève particulier en spécifiant le paramètre userId
, comme indiqué dans l'exemple suivant:
Java
Python
Les élèves sont identifiés par l'identifiant unique ou l'adresse e-mail de l'utilisateur, tel qu'indiqué par le SDK Admin de Google. L'utilisateur actuel peut également faire référence à son propre ID à l'aide du raccourci "me"
.
Il est également possible de recevoir des devoirs pour tous les devoirs d'un cours. Pour ce faire, utilisez le littéral "-"
comme courseWorkId
, comme illustré dans l'exemple suivant:
Java
service.courses().courseWork().studentSubmissions()
.list(courseId, "-")
.set("userId", userId)
.execute();
Python
service.courses().courseWork().studentSubmissions().list(
courseId=<course ID or alias>,
courseWorkId='-',
userId=<user ID>).execute()
Le champ d'application requis dépend du rôle que possède l'utilisateur à l'origine de la demande dans le cours. Utilisez le champ d'application suivant si l'utilisateur est un enseignant ou un administrateur de domaine:
https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students
Utilisez le champ d'application suivant si l'utilisateur est un élève:
https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me
L'autorisation de récupérer le travail d'un élève n'implique pas l'autorisation d'accéder aux pièces jointes ou aux métadonnées associées. En pratique, cela signifie qu'un administrateur peut ne pas voir le titre d'un fichier Drive joint s'il n'est pas membre du cours. Si vous souhaitez autoriser les administrateurs à accéder aux fichiers des utilisateurs, consultez le guide de délégation au niveau du domaine.
Ajouter des pièces jointes à une réponse d'élève
Vous pouvez joindre des liens à un devoir d'élève en joignant une ressource Link
, DriveFile
ou YouTubeVideo
. Pour ce faire, utilisez courses.courseWork.studentSubmissions.modifyAttachments
, comme illustré dans l'exemple suivant:
Java
Python
Une pièce jointe de lien est définie par l'URL cible. Classroom extrait automatiquement le titre et la vignette. Pour en savoir plus sur les autres documents, consultez leurs pages de référence respectives.
Le StudentSubmission
ne peut être modifié que par un enseignant de cours ou par l'élève auquel il appartient. Vous ne pouvez joindre un élément Materials
que si l'élément CourseWorkType
du devoir envoyé par l'élève est ASSIGNMENT
.
Le champ d'application requis dépend du rôle que possède l'utilisateur à l'origine de la demande dans le cours. Utilisez le champ d'application suivant si l'utilisateur est un enseignant:
https://www.googleapis.com/auth/classroom.coursework.students
Utilisez le champ d'application suivant si l'utilisateur est un élève:
https://www.googleapis.com/auth/classroom.coursework.me
Gérer l'état des réponses des élèves
La réponse d'un élève peut être annulée, remise ou rendue. Le champ d'état dans StudentSubmission
indique l'état actuel. Pour modifier l'état, appelez l'une des méthodes suivantes:
courses.courseWork.studentSubmissions.turnIn
courses.courseWork.studentSubmissions.return
courses.courseWork.studentSubmissions.reclaim
Toutes ces méthodes utilisent un corps vide. Exemple :
Java
Python
service.courses().courseWork().studentSubmission().turnIn(
courseId=<course ID or alias>,
courseWorkId=<courseWork ID>,
id=<studentSubmission ID>,
body={}).execute()
Seul l'élève propriétaire d'une StudentSubmission
peut la rendre ou la récupérer.
Seul un envoi remis peut être récupéré. Les enseignants de cours ne peuvent renvoyer qu'un objet StudentSubmission
dont l'état est rendu.
Noter les réponses des élèves
La ressource StudentSubmission
comporte deux champs permettant de stocker les notes : assignedGrade
, qui est la note transmise aux élèves, et draftGrade
, une note provisoire visible uniquement par les enseignants. Ces champs sont mis à jour à l'aide de courses.courseWork.studentSubmissions.patch
avec un masque de champ contenant les champs appropriés, comme illustré dans l'exemple suivant.
Java
Python
studentSubmission = {
'assignedGrade': 99,
'draftGrade': 80
}
service.courses().courseWork().studentSubmissions().patch(
courseId=<course ID or alias>,
courseWorkId=<courseWork ID>,
id=<studentSubmission ID>,
updateMask='assignedGrade,draftGrade',
body=studentSubmission).execute()
Avec l'interface utilisateur Classroom, les enseignants ne peuvent pas attribuer de note tant qu'ils n'ont pas enregistré une note temporaire. La note attribuée peut ensuite être renvoyée à un élève. Les applications doivent émuler ce comportement. Votre application peut noter le devoir d'un élève de deux manières:
Attribuez uniquement
draftGrade
. Cela permet, par exemple, de permettre à l'enseignant de vérifier manuellement les notes avant de les finaliser. Les élèves ne peuvent pas voir les notes temporaires.Attribuez les
draftGrade
et l'assignedGrade
pour noter complètement un devoir.
Lister les notes attribuées
Vous pouvez répertorier toutes les notes pour un élément de devoir particulier en explorant l'objet de réponse de la méthode courses.courseWork.studentSubmissions.list
:
Java
Python
response = coursework.studentSubmissions().list(
courseId=course_id,
courseWorkId=coursework_id,
pageSize=10).execute()
submissions.extend(response.get('studentSubmissions', []))
if not submissions:
print('No student submissions found.')
print('Student Submissions:')
for submission in submissions:
print(f"Submitted at:"
f"{(submission.get('userId'), submission.get('assignedGrade'))}")