Un rubric est un modèle que les enseignants peuvent utiliser pour noter les devoirs des élèves. L'API Classroom vous permet d'agir au nom de l'enseignant pour gérer ces grilles d'évaluation.
Figure 1. Vue d'un exemple de grille d'évaluation sur un devoir Classroom
Ce guide décrit les concepts de base et les fonctionnalités de l'API Rubrics. Consultez ces articles du centre d'aide pour en savoir plus sur la structure générale d'une grille d'évaluation et sur la notation de base dans l'interface utilisateur de Classroom.
Conditions préalables
Ce guide suppose que vous disposez des éléments suivants:
- Python 3.8.6 ou version ultérieure
- L'outil de gestion des packages pip
- un projet Google Cloud ;
- Un compte Google Workspace for Education sur lequel Google Classroom est activé
- Une classe test avec au moins un compte élève test Si vous n'avez pas de cours Classroom permettant d'effectuer des tests, créez-en un dans l'interface utilisateur et ajoutez un élève test.
Autoriser les identifiants pour une application de bureau
Pour vous authentifier en tant qu'utilisateur final et accéder aux données utilisateur dans votre application, vous devez créer un ou plusieurs ID client OAuth 2.0. Un ID client sert à identifier une application unique auprès des serveurs OAuth de Google. Si votre application s'exécute sur plusieurs plates-formes, vous devez créer un ID client distinct pour chaque plate-forme.
- Accédez à la page Identifiants GCP dans la console Google Cloud.
- Cliquez sur Créer des identifiants > ID client OAuth.
- Cliquez sur Type d'application > Application de bureau.
- Dans le champ Name (Nom), saisissez le nom de l'identifiant. Ce nom n'est affiché que dans la console Google Cloud. Par exemple, "Client de l'aperçu des grilles d'évaluation".
- Cliquez sur Créer. L'écran du client OAuth créé s'affiche, affichant votre nouvel ID client et votre nouveau code secret du client.
- Cliquez sur Télécharger JSON, puis sur OK. Les nouveaux identifiants apparaissent sous "ID client OAuth 2.0".
- Enregistrez le fichier JSON téléchargé sous le nom
credentials.json, puis déplacez-le dans votre répertoire de travail. - Cliquez sur Créer des identifiants > Clé API et notez la clé API.
Pour en savoir plus, consultez Créer des identifiants d'accès.
Configurer les champs d'application OAuth
En fonction des champs d'application OAuth existants de votre projet, vous devrez peut-être configurer d'autres champs d'application.
- Accédez à l'écran d'autorisation OAuth.
- Cliquez sur Edit App > Save and Continue (Modifier l'application > Enregistrer et continuer) pour accéder à l'écran "Scopes" (Champs d'application).
- Cliquez sur Ajouter ou supprimer des champs d'application.
- Si vous ne l'avez pas encore fait, ajoutez les champs d'application suivants :
https://www.googleapis.com/auth/classroom.coursework.studentshttps://www.googleapis.com/auth/classroom.courses
- Cliquez ensuite sur Mettre à jour > Enregistrer et continuer > Enregistrer et continuer > Revenir au tableau de bord.
Pour en savoir plus, consultez la section Configurer l'écran de consentement OAuth.
Le champ d'application classroom.coursework.students permet l'accès en lecture et en écriture aux grilles d'évaluation (ainsi que l'accès à CourseWork), et le champ d'application classroom.courses permet l'accès à des cours de lecture et d'écriture.
Les champs d'application requis pour une méthode donnée sont répertoriés dans la documentation de référence de la méthode. Consultez l'exemple Champs d'application des autorisations courses.courseWork.rubrics.create. Vous pouvez voir tous les champs d'application Classroom dans la section Champs d'application OAuth 2.0 pour les API Google. Les grilles d'évaluation ne sont pas mentionnées ici, car l'API est encore en version preview.
Configurer l'exemple
Dans votre répertoire de travail, installez la bibliothèque cliente Google pour Python:
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
Créez un fichier nommé main.py qui compile la bibliothèque cliente et autorise l'utilisateur en utilisant votre clé API à la place de YOUR_API_KEY:
import json
import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
# If modifying these scopes, delete the file token.json.
SCOPES = ['https://www.googleapis.com/auth/classroom.courses',
'https://www.googleapis.com/auth/classroom.coursework.students']
def build_authenticated_service(api_key):
"""Builds the Classroom service."""
creds = None
# The file token.json stores the user's access and refresh tokens, and is
# created automatically when the authorization flow completes for the first
# time.
if os.path.exists('token.json'):
creds = Credentials.from_authorized_user_file('token.json', SCOPES)
# If there are no (valid) credentials available, let the user log in.
if not creds or not creds.valid:
if creds and creds.expired and creds.refresh_token:
creds.refresh(Request())
else:
flow = InstalledAppFlow.from_client_secrets_file(
'credentials.json', SCOPES)
creds = flow.run_local_server(port=0)
# Save the credentials for the next run.
with open('token.json', 'w') as token:
token.write(creds.to_json())
try:
# Build the Classroom service.
service = build(
serviceName="classroom",
version="v1",
credentials=creds,
discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key={api_key}")
return service
except HttpError as error:
print('An error occurred: %s' % error)
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
Exécutez le script à l'aide de python main.py. Vous devriez être invité à vous connecter et à accepter les champs d'application OAuth.
Créer un devoir
Une grille d'évaluation est associée à un devoir, ou CourseWork, et n'a de sens que dans le contexte de cette CourseWork. Les grilles d'évaluation ne peuvent être créées que par le projet Google Cloud qui a créé l'élément parent CourseWork. Pour les besoins de ce guide, créez une attribution CourseWork avec un script.
Ajoutez le code suivant à main.py :
def get_latest_course(service):
"""Retrieves the last created course."""
try:
response = service.courses().list(pageSize=1).execute()
courses = response.get("courses", [])
if not courses:
print("No courses found. Did you remember to create one in the UI?")
return
course = courses[0]
return course
except HttpError as error:
print(f"An error occurred: {error}")
return error
def create_coursework(service, course_id):
"""Creates and returns a sample coursework."""
try:
coursework = {
"title": "Romeo and Juliet analysis.",
"description": """Write a paper arguing that Romeo and Juliet were
time travelers from the future.""",
"workType": "ASSIGNMENT",
"state": "PUBLISHED",
}
coursework = service.courses().courseWork().create(
courseId=course_id, body=coursework).execute()
return coursework
except HttpError as error:
print(f"An error occurred: {error}")
return error
À présent, mettez à jour main.py pour récupérer le course_id de la classe de test que vous venez de créer, créez un exemple de devoir et récupérez le coursework_id du devoir:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
course = get_latest_course(service)
course_id = course.get("id")
course_name = course.get("name")
print(f"'{course_name}' course ID: {course_id}")
coursework = create_coursework(service, course_id)
coursework_id = coursework.get("id")
print(f"Assignment created with ID {coursework_id}")
#TODO(developer): Save the printed course and coursework IDs.
Enregistrez course_id et coursework_id. Ceux-ci sont nécessaires pour toutes les opérations CRUD des rubriques d'évaluation.
Vous devriez maintenant disposer d'un exemple de CourseWork dans Classroom.
Figure 2 : Vue d'un exemple de devoir dans Classroom
Créer une grille d'évaluation
Vous êtes maintenant prêt à gérer des grilles d'évaluation.
Vous pouvez créer une grille d'évaluation dans un CourseWork avec un appel Create contenant l'objet de grille d'évaluation complet, où les propriétés d'ID des critères et des niveaux sont omises (générées lors de la création).
Ajoutez la fonction suivante à main.py:
def create_rubric(service, course_id, coursework_id):
"""Creates an example rubric on a coursework."""
try:
body = {
"criteria": [
{
"title": "Argument",
"description": "How well structured your argument is.",
"levels": [
{"title": "Convincing",
"description": "A compelling case is made.", "points": 30},
{"title": "Passable",
"description": "Missing some evidence.", "points": 20},
{"title": "Needs Work",
"description": "Not enough strong evidence..", "points": 0},
]
},
{
"title": "Spelling",
"description": "How well you spelled all the words.",
"levels": [
{"title": "Perfect",
"description": "No mistakes.", "points": 20},
{"title": "Great",
"description": "A mistake or two.", "points": 15},
{"title": "Needs Work",
"description": "Many mistakes.", "points": 5},
]
},
{
"title": "Grammar",
"description": "How grammatically correct your sentences are.",
"levels": [
{"title": "Perfect",
"description": "No mistakes.", "points": 20},
{"title": "Great",
"description": "A mistake or two.", "points": 15},
{"title": "Needs Work",
"description": "Many mistakes.", "points": 5},
]
},
]
}
rubric = service.courses().courseWork().rubrics().create(
courseId=course_id, courseWorkId=coursework_id, body=body,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Ensuite, mettez à jour et exécutez main.py pour créer l'exemple de grille d'évaluation en utilisant vos ID Course et CourseWork précédents:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(rubric, indent=4))
Quelques points sur la représentation de la grille d’évaluation:
- Le critère et l'ordre des niveaux sont reflétés dans l'interface utilisateur de Classroom.
- Les niveaux notés (ceux avec la propriété
points) doivent être triés par points, dans l'ordre croissant ou décroissant (ils ne peuvent pas être triés de manière aléatoire). - Les enseignants peuvent trier de nouveau les critères et les niveaux notés (mais pas les niveaux non notés) dans l'interface utilisateur, ce qui modifie l'ordre dans les données.
Pour en savoir plus sur la structure des grilles d'évaluation, consultez les limites.
De retour dans l'interface utilisateur, vous devriez voir la grille d'évaluation sur le devoir.
Figure 3 : Vue d'un exemple de grille d'évaluation sur un devoir Classroom
Lire une grille d'évaluation
Les grilles d'évaluation peuvent être lues à l'aide des méthodes List et Get standards.
Un devoir ne peut contenir qu'une seule grille d'évaluation. Par conséquent, List peut sembler peu intuitif, mais il peut être utile si vous ne connaissez pas déjà l'ID de la grille d'évaluation. Si aucune grille d'évaluation n'est associée à un élément CourseWork, la réponse List est vide.
Ajoutez la fonction suivante à main.py:
def get_rubric(service, course_id, coursework_id):
"""
Get the rubric on a coursework. There can only be at most one.
Returns null if there is no rubric.
"""
try:
response = service.courses().courseWork().rubrics().list(
courseId=course_id, courseWorkId=coursework_id,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
rubrics = response.get("rubrics", [])
if not rubrics:
print("No rubric found for this assignment.")
return
rubric = rubrics[0]
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Mettez à jour et exécutez main.py pour récupérer la grille d'évaluation que vous avez ajoutée:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(rubric, indent=4))
#TODO(developer): Save the printed rubric ID.
Notez la propriété id dans la grille d'évaluation pour les étapes suivantes.
Get fonctionne bien lorsque vous disposez d'un ID de grille d'évaluation. Utiliser Get dans la fonction peut se présenter comme suit:
def get_rubric(service, course_id, coursework_id, rubric_id):
"""
Get the rubric on a coursework. There can only be at most one.
Returns a 404 if there is no rubric.
"""
try:
rubric = service.courses().courseWork().rubrics().get(
courseId=course_id,
courseWorkId=coursework_id,
id=rubric_id,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Cette implémentation renvoie une erreur 404 en l'absence de grille d'évaluation.
Mettre à jour une grille d'évaluation
Les modifications d'une grille d'évaluation se font via des appels Patch. En raison de la structure complexe d'une grille d'évaluation, les mises à jour doivent être effectuées à l'aide d'un modèle lecture-modification-écriture, dans lequel l'intégralité de la propriété criteria est remplacée.
Les règles de mise à jour sont les suivantes:
- Les critères ou niveaux ajoutés sans ID sont considérés comme des ajouts.
- Les critères ou niveaux manquants auparavant sont considérés comme des suppressions.
- Les critères ou niveaux avec un ID existant, mais des données modifiées sont considérés comme des modifications. Les propriétés non modifiées sont laissées telles quelles.
- Les critères ou niveaux fournis avec des ID nouveaux ou inconnus sont considérés comme des erreurs.
- L'ordre des nouveaux critères et niveaux est considéré comme le nouvel ordre de l'interface utilisateur (avec les limites mentionnées ci-dessus).
Ajouter une fonction pour mettre à jour une grille d'évaluation:
def update_rubric(service, course_id, coursework_id, rubric_id, body):
"""
Updates the rubric on a coursework.
"""
try:
rubric = service.courses().courseWork().rubrics().patch(
courseId=course_id,
courseWorkId=coursework_id,
id=rubric_id,
body=body,
updateMask='criteria',
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Dans cet exemple, le champ criteria est spécifié pour être modifié avec un updateMask.
Modifiez ensuite main.py pour apporter une modification à chacune des règles de mise à jour mentionnées ci-dessus:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
# Get the latest rubric.
rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
criteria = rubric.get("criteria")
"""
The "criteria" property should look like this:
[
{
"id": "NkEyMdMyMzM2Nxkw",
"title": "Argument",
"description": "How well structured your argument is.",
"levels": [
{
"id": "NkEyMdMyMzM2Nxkx",
"title": "Convincing",
"description": "A compelling case is made.",
"points": 30
},
{
"id": "NkEyMdMyMzM2Nxky",
"title": "Passable",
"description": "Missing some evidence.",
"points": 20
},
{
"id": "NkEyMdMyMzM2Nxkz",
"title": "Needs Work",
"description": "Not enough strong evidence..",
"points": 0
}
]
},
{
"id": "NkEyMdMyMzM2Nxk0",
"title": "Spelling",
"description": "How well you spelled all the words.",
"levels": [...]
},
{
"id": "NkEyMdMyMzM2Nxk4",
"title": "Grammar",
"description": "How grammatically correct your sentences are.",
"levels": [...]
}
]
"""
# Make edits. This example will make one of each type of change.
# Add a new level to the first criteria. Levels must remain sorted by
# points.
new_level = {
"title": "Profound",
"description": "Truly unique insight.",
"points": 50
}
criteria[0]["levels"].insert(0, new_level)
# Remove the last criteria.
del criteria[-1]
# Update the criteria titles with numeric prefixes.
for index, criterion in enumerate(criteria):
criterion["title"] = f"{index}: {criterion['title']}"
# Resort the levels from descending to ascending points.
for criterion in criteria:
criterion["levels"].sort(key=lambda level: level["points"])
# Update the rubric with a patch call.
new_rubric = update_rubric(
service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID, YOUR_RUBRIC_ID, rubric)
print(json.dumps(new_rubric, indent=4))
Les modifications devraient maintenant être répercutées dans Classroom pour l'enseignant.
Figure 4. Vue de la grille d'évaluation mise à jour.
Afficher les devoirs notés par grille d'évaluation
Pour le moment, l'API ne peut pas noter les devoirs des élèves à l'aide d'une grille d'évaluation, mais vous pouvez lire les notes correspondantes dans l'interface utilisateur de Classroom.
En tant qu'élève dans l'interface utilisateur de Classroom, terminez et remettez votre exemple de devoir. Ensuite, en tant qu'enseignant, notez manuellement le devoir à l'aide de la grille d'évaluation.
Figure 5. Vue de la grille d'évaluation par les enseignants pendant la notation.
Les devoirs des élèves notés avec une grille d'évaluation ont deux nouvelles propriétés: draftRubricGrades et assignedRubricGrades, qui représentent respectivement les points et les niveaux choisis par l'enseignant pendant le brouillon et l'état de notation attribué.
De plus, les devoirs des élèves associés à une grille d'évaluation contiennent un champ rubricId, avant même la notation. Il s'agit de la dernière grille d'évaluation associée à CourseWork. Cette valeur peut changer si les enseignants suppriment et recréent une grille d'évaluation.
Vous pouvez utiliser les méthodes studentSubmissions.Get et studentSubmissions.List existantes pour afficher les devoirs notés.
Ajoutez la fonction suivante à main.py pour répertorier les devoirs des élèves:
def get_latest_submission(service, course_id, coursework_id):
"""Retrieves the last submission for an assignment."""
try:
response = service.courses().courseWork().studentSubmissions().list(
courseId = course_id,
courseWorkId = coursework_id,
pageSize=1,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
submissions = response.get("studentSubmissions", [])
if not submissions:
print(
"""No submissions found. Did you remember to turn in and grade
the assignment in the UI?""")
return
submission = submissions[0]
return submission
except HttpError as error:
print(f"An error occurred: {error}")
return error
Ensuite, mettez à jour et exécutez main.py pour afficher les notes envoyées.
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
submission = get_latest_submission(
service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(submission, indent=4))
draftRubricGrades et assignedRubricGrades contiennent:
- Le
criterionIddes critères de la grille d'évaluation correspondants. - La valeur
pointsattribuée par l'enseignant pour chaque critère. Il peut s'agir du niveau sélectionné, mais l'enseignant aurait également pu l'écraser. - La
levelIddu niveau choisi pour chaque critère. Si l'enseignant n'a pas choisi de niveau, mais qu'il a quand même attribué des points au critère, ce champ n'est pas présent.
Ces listes ne contiennent des entrées que pour les critères selon lesquels un enseignant a sélectionné un niveau ou des points de repère. Par exemple, si un enseignant choisit d'interagir avec un seul critère lors de la notation, draftRubricGrades et assignedRubricGrades ne comportent qu'un seul élément, même si la grille d'évaluation comporte de nombreux critères.
Supprimer une grille d'évaluation
Vous pouvez supprimer une grille d'évaluation à l'aide d'une requête Delete standard. Le code suivant présente un exemple de fonction d'exhaustivité, mais comme la notation a déjà commencé, vous ne pouvez pas supprimer la grille d'évaluation actuelle:
def delete_rubric(service, course_id, coursework_id, rubric_id):
"""Deletes the rubric on a coursework."""
try:
service.courses().courseWork().rubrics().delete(
courseId=course_id,
courseWorkId=coursework_id,
id=rubric_id,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
except HttpError as error:
print(f"An error occurred: {error}")
return error
Exporter et importer des grilles d'évaluation
Les grilles d'évaluation peuvent être exportées manuellement vers des feuilles de calcul Google afin que les enseignants puissent les réutiliser.
En plus de spécifier les critères de grille d'évaluation dans le code, il est possible de créer et de mettre à jour des grilles d'évaluation à partir de ces feuilles exportées en spécifiant sourceSpreadsheetId dans le corps d'une grille d'évaluation au lieu de criteria:
def create_rubric_from_sheet(service, course_id, coursework_id, sheet_id):
"""Creates an example rubric on a coursework."""
try:
body = {
"sourceSpreadsheetId": sheet_id
}
rubric = service.courses().courseWork().rubrics().create(
courseId=course_id, courseWorkId=coursework_id, body=body,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Commentaires
Si vous rencontrez des problèmes ou si vous avez des commentaires, envoyez-nous vos commentaires.