Un rubric est un modèle que les enseignants peuvent utiliser pour noter les élèves
envois. L'API Classroom vous permet d'agir pour le compte
à un enseignant de gérer
ces grilles d'évaluation.
Figure 1 : Vue d'un exemple de grille d'évaluation pour un devoir Classroom
Ce guide décrit les concepts de base et les fonctionnalités de l'API Rubrics. Voir ces articles du centre d'aide pour en savoir plus sur la générale structure d'une grille d'évaluation et comment la grille d'évaluation de notation dans l'interface utilisateur de Classroom.
Prérequis
Ce guide suppose que vous disposez des éléments suivants:
- Python 3.8.6 ou version ultérieure
- L'outil de gestion de packages pip
- un projet Google Cloud ;
- Un compte Google Workspace for Education associé à Google Classroom activé.
- Un cours avec au moins un compte élève test Si vous ne disposez pas d'un à des fins de test, créez-en un dans l'UI et ajouter un élève test.
Autoriser des 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 Google Cloud dans le console Google Cloud.
- Cliquez sur Create Credentials (Créer des identifiants) > ID client OAuth :
- Cliquez sur Type d'application > Application de bureau :
- Dans le champ Nom, saisissez un nom pour l'identifiant. Ce nom est uniquement comme indiqué dans la console Google Cloud. Par exemple, "Client de la prévisualisation des grilles d'évaluation".
- Cliquez sur Créer. L'écran "Client OAuth créé" s'affiche. Il contient vos nouvelles l'ID client et le code secret du client ;
- Cliquez sur Download JSON (Télécharger JSON), puis sur OK. Identifiant que vous venez de créer s'affiche sous "ID client OAuth 2.0".
- Enregistrez le fichier JSON téléchargé sous le nom
credentials.json, puis déplacez-le vers votre répertoire de travail. - Cliquez sur Create Credentials (Créer des identifiants) > Clé API, puis 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 habilitations OAuth existantes de votre projet, vous devrez peut-être configurer champs d'application supplémentaires.
- Accédez à l'écran de consentement OAuth.
- Cliquez sur Modifier l'application > Cliquez sur Save and Continue (Enregistrer et continuer) pour accéder à l'écran "Scopes" (Champs d'application).
- Cliquez sur Ajouter ou supprimer des habilitations.
- Ajoutez les habilitations suivantes, si ce n'est pas déjà fait:
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 Configurer l'écran de consentement OAuth. plus encore.
Le champ d'application classroom.coursework.students permet d'accéder en lecture et en écriture
grilles d'évaluation (avec accès à CourseWork) et le champ d'application classroom.courses
permet des cours de lecture et d'écriture.
Les champs d'application requis pour une méthode donnée sont listés dans la documentation de référence.
pour la méthode. Voir courses.courseWork.rubrics.create habilitations d'autorisation
à titre d'exemple. Vous pouvez consulter toutes les habilitations Classroom dans les habilitations OAuth 2.0 pour Google
API. 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 le
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
autoriser les habilitations OAuth.
Créer un devoir
Une grille d'évaluation est associée à un devoir, ou CourseWork, et n'est
significatif dans le contexte de ce CourseWork. Les grilles d'évaluation ne peuvent être créées
Le projet Google Cloud qui a créé l'élément CourseWork parent Aux fins du
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éé, créer un exemple de devoir et récupérer les
coursework_id:
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. Ces éléments sont nécessaires pour toutes les grilles d'évaluation CRUD
opérations.
Vous devriez maintenant disposer d'un exemple de CourseWork dans Classroom.
Figure 2 : Affichage d'un exemple de devoir dans Classroom
Créer une grille d'évaluation
Vous êtes maintenant prêt à gérer les grilles d'évaluation.
Vous pouvez créer une grille d'évaluation sur une CourseWork avec un appel Create contenant les
objet de grille d'évaluation complet, où les propriétés d'ID des critères et des niveaux sont omises
(ils sont générés 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 à l'aide de votre Course.
et CourseWork de tout à l'heure:
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))
Voici quelques points à retenir concernant la représentation de la grille d'évaluation:
- Les critères 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 ordonnés au hasard). - Les enseignants peuvent modifier les critères et les niveaux notés (mais pas les éléments non notés niveaux) dans l'interface utilisateur, ce qui modifie leur ordre dans les données.
Consultez les limites pour prendre connaissance d'autres mises en garde concernant la structure des grilles d'évaluation.
De retour dans l'interface utilisateur, vous devriez voir la grille d'évaluation du devoir.
Figure 3 : Vue d'un exemple de grille d'évaluation pour 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 comporter qu'une seule grille d'évaluation. Par conséquent, List peut sembler être
peu intuitive, mais elle peut s'avérer utile si vous ne disposez pas encore de l'ID de la grille d'évaluation. S'il y a
n'est pas associée à une grille d'évaluation 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 avec l'ID de la grille d'évaluation. Utiliser Get dans la fonction
à la place, il 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 apportées à une grille d'évaluation se font via des appels Patch. En raison de sa structure complexe,
d'une grille d'évaluation, les mises à jour doivent se faire selon un modèle lecture-modification-écriture, où le
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 ajouts.
- Les critères ou niveaux manquant auparavant sont pris en compte les suppressions.
- Les critères ou niveaux ayant un ID existant, mais des données modifiées sont pris en compte. modifications. Les propriétés non modifiées sont laissées telles quelles.
- Les critères ou les niveaux fournis avec des identifiants nouveaux ou inconnus sont considérés .
- 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 permettant de 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 une modification avec un
updateMask
Ensuite, modifiez main.py pour apporter un changement à chacune des mises à jour susmentionnées.
règles:
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 à présent ê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 une grille d'évaluation
Pour l'instant, les devoirs des élèves ne peuvent pas être notés avec une grille d'évaluation par l'API, mais vous peuvent lire les notes des devoirs qui ont été notés à l'aide d'une grille d'évaluation dans l'UI de Classroom.
En tant qu'élève, terminez et remettez votre exemple de devoir dans l'interface utilisateur de Classroom. Ensuite, en tant qu'enseignant, notez manuellement le devoir à l'aide de la grille d'évaluation.
Figure 5. Vue de la grille d'évaluation pour les enseignants pendant la notation.
Les devoirs d'élèves notés à l'aide d'une grille d'évaluation comportent deux nouveaux
: draftRubricGrades et assignedRubricGrades, qui représentent le
points et niveaux choisis par l'enseignant lors du brouillon et de la notation attribuée
, respectivement.
De plus, les devoirs des élèves auxquels une grille d'évaluation est associée contiennent un élément rubricId.
avant même de procéder à 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
grille d'évaluation.
Vous pouvez utiliser les studentSubmissions.Get et
studentSubmissions.List méthodes 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 attribué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 les éléments suivants:
criterionIddes critères correspondants de la grille d'évaluation.pointsattribué par l'enseignant pour chaque critère. Il peut s'agir niveau sélectionné, mais l'enseignant peut aussi l'avoir remplacé.levelIddu niveau choisi pour chaque critère. Si l'enseignant n'a pas un niveau, tout en continuant à attribuer des points au critère, ce champ est absente.
Ces listes ne contiennent que des entrées pour les critères selon lesquels un enseignant :
sélectionné un niveau ou des points de consigne. Par exemple, si un enseignant choisit
interagissent avec un critère pendant la notation, draftRubricGrades et
assignedRubricGrades ne comporterait 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 avec une demande Delete standard. Le code suivant
présente un exemple de fonction d'exhaustivité, mais comme la notation a déjà
a 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
Vous pouvez exporter manuellement les grilles d'évaluation vers Google Des feuilles de calcul que les enseignants peuvent réutiliser
En plus de spécifier les critères de la grille d'évaluation dans le code, il est possible de créer et
mettre à jour les grilles d'évaluation à partir de ces feuilles exportées en spécifiant le
sourceSpreadsheetId dans le corps de la 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 souhaitez nous faire part de vos commentaires, envoyez-nous vos commentaires.