Eine rubric ist eine Vorlage, die Lehrkräfte beim Benoten von Schüler-/Studentenarbeiten verwenden können. Mit der Classroom API können Sie im Namen des Lehrkräften diese Bewertungsraster verwalten und die Noten aus den Bewertungsrastern für die Einreichungen der Schüler/Studenten lesen.
Abbildung 1. Beispiel für ein Bewertungsschema für eine Classroom-Aufgabe
In diesem Leitfaden werden die grundlegenden Konzepte und Funktionen der Rubrics API erläutert. In diesen Hilfeartikeln erfahren Sie mehr über die allgemeine Struktur einer Benotungsskala und wie die Benotung mithilfe einer Benotungsskala in der Classroom-Benutzeroberfläche funktioniert.
Vorbereitung
In diesem Leitfaden wird davon ausgegangen, dass Sie Folgendes haben:
- Python 3.8.6 oder höher
- Das Paketverwaltungstool pip
- Ein Google Cloud-Projekt
- Ein Google Workspace for Education-Konto, in dem Google Classroom aktiviert ist und dem eine Google Workspace for Education Plus-Lizenz zugewiesen ist. Wenn Sie noch kein Entwickler-Demokonto haben, können Sie ein Upgrade beantragen.
- Einen Testkurs mit mindestens einem Test-Schüler-/Studentenkonto. Wenn Sie keine Classroom-Kurs haben, die Sie für Tests verwenden können, erstellen Sie einen in der Benutzeroberfläche und fügen Sie einen Teststudenten hinzu.
Anmeldedaten für eine Desktopanwendung autorisieren
Für die Authentifizierung als Endnutzer und für den Zugriff auf Nutzerdaten in Ihrer Anwendung müssen Sie mindestens eine OAuth 2.0-Client-ID erstellen. Eine Client-ID wird zur Identifizierung einer einzelnen Anwendung bei Googles OAuth-Servern verwendet. Wenn Ihre App auf mehreren Plattformen ausgeführt wird, müssen Sie für jede Plattform eine separate Client-ID erstellen.
- Rufen Sie in der Google Cloud Console die Seite „Anmeldedaten“ auf.
- Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
- Klicken Sie auf Anwendungstyp > Desktop-App.
- Geben Sie im Feld Name einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google Cloud Console angezeigt. Beispiel: „Rubrics-Client“.
- Klicken Sie auf Erstellen. Der Bildschirm „OAuth-Client erstellt“ wird angezeigt. Darauf sind Ihre neue Client-ID und Ihr Clientschlüssel zu sehen.
- Klicken Sie auf JSON herunterladen und dann auf OK. Die neu erstellten Anmeldedaten werden unter „OAuth 2.0-Client-IDs“ angezeigt.
- Speichern Sie die heruntergeladene JSON-Datei als
credentials.jsonund verschieben Sie sie in Ihr Arbeitsverzeichnis. - Klicken Sie auf Anmeldedaten erstellen > API-Schlüssel und notieren Sie sich den API-Schlüssel.
Weitere Informationen finden Sie unter Anmeldedaten für den Zugriff erstellen.
OAuth-Bereiche konfigurieren
Je nach vorhandenen OAuth-Bereichen Ihres Projekts müssen Sie möglicherweise zusätzliche Bereiche konfigurieren.
- Rufen Sie den OAuth-Zustimmungsbildschirm auf.
- Klicken Sie auf App bearbeiten > Speichern und fortfahren, um den Bildschirm „Bereiche“ aufzurufen.
- Klicken Sie auf Bereiche hinzufügen oder entfernen.
- Fügen Sie die folgenden Bereiche hinzu, falls noch nicht geschehen:
https://www.googleapis.com/auth/classroom.coursework.studentshttps://www.googleapis.com/auth/classroom.courses
- Klicken Sie dann auf Aktualisieren > Speichern und fortfahren > Speichern und fortfahren > Zurück zum Dashboard.
Weitere Informationen finden Sie unter OAuth-Zustimmungsbildschirm konfigurieren.
Mit dem Bereich classroom.coursework.students können Sie neben dem Zugriff auf CourseWork auch Lese- und Schreibzugriff auf Rubriken erhalten. Mit dem Bereich classroom.courses können Sie Kurse lesen und schreiben.
Die für eine bestimmte Methode erforderlichen Bereiche sind in der Referenzdokumentation für die Methode aufgeführt. Weitere Informationen finden Sie unter courses.courseWork.rubrics.create Autorisierungsbereiche. Alle Bereiche für Classroom finden Sie unter OAuth 2.0-Bereiche für Google APIs.
Beispiel konfigurieren
Installieren Sie die Google-Clientbibliothek für Python in Ihrem Arbeitsverzeichnis:
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
Erstellen Sie eine Datei namens main.py, in der die Clientbibliothek erstellt und der Nutzer autorisiert wird. Verwenden Sie dabei Ihren API-Schlüssel anstelle von 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)
Führen Sie das Script mit python main.py aus. Sie werden aufgefordert, sich anzumelden und Ihre Einwilligung für OAuth-Bereiche zu erteilen.
Aufgabe erstellen
Eine Benotungsskala ist mit einer Aufgabe oder CourseWork verknüpft und nur im Kontext dieser CourseWork sinnvoll. Überschriften können nur im Google Cloud-Projekt erstellt werden, in dem das übergeordnete CourseWork-Element erstellt wurde. Erstellen Sie für die Zwecke dieses Leitfadens eine neue CourseWork-Aufgabe mit einem Script.
Fügen Sie main.py Folgendes hinzu:
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
Aktualisieren Sie jetzt main.py, um die course_id der gerade erstellten Testklasse abzurufen, erstellen Sie eine neue Beispielaufgabe und rufen Sie die coursework_id der Aufgabe ab:
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.
Speichern Sie die course_id und coursework_id. Sie sind für alle CRUD-Vorgänge (Create, Read, Update, Delete) für Rubriken erforderlich.
Sie sollten jetzt eine Beispieldatei CourseWork in Classroom haben.
Abbildung 2. Beispiel für eine Aufgabe in Classroom
Voraussetzungen für Nutzer prüfen
Zum Erstellen und Aktualisieren von Benotungsrastern muss sowohl dem Nutzer, der den Antrag stellt, als auch dem entsprechenden Kursinhaber eine Google Workspace for Education Plus-Lizenz zugewiesen sein. Classroom unterstützt einen Berechtigungsendpunkt, mit dem Entwickler die Funktionen ermitteln können, auf die ein Nutzer Zugriff hat.
Aktualisieren und führen Sie main.py aus, um zu prüfen, ob Ihr Testkonto Zugriff auf die Funktion „Bewertungsschemata“ hat:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
print('User eligible for rubrics creation.')
Bewertungsschema erstellen
Jetzt können Sie mit dem Verwalten von Benotungsrastern beginnen.
Ein Bewertungsschema kann auf einem CourseWork mit einem create()-Aufruf erstellt werden, der das vollständige Bewertungsschemaobjekt enthält. Dabei werden die ID-Eigenschaften für Kriterien und Stufen weggelassen, da sie beim Erstellen generiert werden.
Fügen Sie main.py die folgende Funktion hinzu:
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
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Aktualisieren Sie dann main.py und führen Sie es aus, um die Beispielbenotung mit den zuvor verwendeten Course- und CourseWork-IDs zu erstellen:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(rubric, indent=4))
Einige Punkte zur Darstellung der Bewertungsskala:
- Die Reihenfolge der Kriterien und Stufen wird in der Classroom-Benutzeroberfläche berücksichtigt.
- Stufen mit Bewertung (mit der
points-Eigenschaft) müssen nach Punkten in aufsteigender oder absteigender Reihenfolge sortiert werden. Eine Zufallssortierung ist nicht zulässig. - Lehrkräfte können Kriterien und benotete Stufen (aber keine unbenoteten Stufen) auf der Benutzeroberfläche neu sortieren. Dadurch ändert sich die Reihenfolge in den Daten.
Weitere Informationen zur Struktur von Beurteilungsrastern finden Sie unter Einschränkungen.
In der Benutzeroberfläche sollte jetzt die Benotungsskala für die Aufgabe angezeigt werden.
Abbildung 3 Beispiel für ein Bewertungsschema für eine Classroom-Aufgabe
Bewertungsschema lesen
Rubriken können mit den Standardmethoden list() und get() gelesen werden.
Eine Aufgabe kann höchstens eine Benotungsskala haben. Daher mag list() unintuitiv erscheinen. Es ist jedoch hilfreich, wenn Sie die Benotungsskala-ID noch nicht haben. Wenn mit einer CourseWork keine Bewertungsskala verknüpft ist, ist die list()-Antwort leer.
Fügen Sie main.py die folgende Funktion hinzu:
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
).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
Aktualisieren und führen Sie main.py aus, um das hinzugefügte Bewertungsschema abzurufen:
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.
Notieren Sie sich das Attribut id in der Tabelle für spätere Schritte.
Get() funktioniert gut, wenn Sie die ID der Benotungsskala haben. Die Verwendung von get() in der Funktion könnte so aussehen:
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
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Bei dieser Implementierung wird 404 zurückgegeben, wenn keine Beurteilungsrichtlinie vorhanden ist.
Bewertungsschema aktualisieren
Aktualisierungen an einer Beurteilungsübersicht werden mit patch()-Aufrufen vorgenommen. Aufgrund der komplexen Struktur einer Beurteilung müssen Aktualisierungen mit einem Lese-Ändern-Schreiben-Muster durchgeführt werden, bei dem die gesamte criteria-Eigenschaft ersetzt wird.
Die Aktualisierungsregeln sind:
- Kriterien oder Ebenen, die ohne ID hinzugefügt werden, gelten als Zusätze.
- Kriterien oder Stufen, die zuvor vorhanden waren, werden als Löschungen betrachtet.
- Kriterien oder Ebenen mit einer vorhandenen ID, aber geänderten Daten gelten als Änderungen. Unveränderte Properties bleiben unverändert.
- Kriterien oder Ebenen, die mit neuen oder unbekannten IDs angegeben werden, gelten als Fehler.
- Die Reihenfolge der neuen Kriterien und Stufen wird als neue Reihenfolge der Benutzeroberfläche betrachtet (mit den oben genannten Einschränkungen).
So fügen Sie eine Funktion zum Aktualisieren eines Bewertungsschemas hinzu:
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'
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
In diesem Beispiel wird das Feld criteria mit einem updateMask zur Änderung angegeben.
Ändern Sie dann main.py, um eine Änderung für jede der oben genannten Aktualisierungsregeln vorzunehmen:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
# 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))
Die Änderungen sollten jetzt für die Lehrkraft in Classroom sichtbar sein.
Abbildung 4 Die aktualisierte Benotungsskala.
Anhand von Bewertungsschema benotete Aufgaben ansehen
Derzeit können die Abgaben von Schülern/Studenten nicht über die API anhand eines Bewertungsschemas benotet werden. Sie können sich aber die Noten für Abgaben ansehen, die in der Classroom-Benutzeroberfläche anhand eines Bewertungsschemas benotet wurden.
Als Schüler oder Student erledigen Sie die Beispielaufgabe in der Classroom-Benutzeroberfläche und geben Sie sie ab. Als Lehrkraft können Sie die Aufgabe dann manuell mithilfe des Bewertungsschemas benoten.
Abbildung 5 Ansicht des Bewertungsschemas für Lehrkräfte während der Benotung
StudentSubmissions, die mit einer Benotungsskala benotet wurden, haben zwei neue Eigenschaften: draftRubricGrades und assignedRubricGrades. Sie stehen für die Punkte und Stufen, die die Lehrkraft im Entwurf ausgewählt und die Benotungsstatus, die ihr zugewiesen wurden.
Sie können die vorhandenen Methoden studentSubmissions.get() und studentSubmissions.list() verwenden, um benotete Einreichungen aufzurufen.
Fügen Sie main.py die folgende Funktion hinzu, um die Einreichungen der Schüler/Studenten aufzulisten:
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
).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
Aktualisieren Sie dann main.py und führen Sie es aus, um die Noten für die Einreichungen aufzurufen.
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 und assignedRubricGrades enthalten Folgendes:
- Die
criterionIdder entsprechenden Bewertungskriterien. - Die
points, die die Lehrkraft für jedes Kriterium zugewiesen hat. Das kann an der ausgewählten Stufe liegen, aber auch daran, dass die Lehrkraft den Wert überschrieben hat. - Die
levelIdder für jedes Kriterium ausgewählten Stufe. Wenn die Lehrkraft kein Niveau ausgewählt, aber trotzdem Punkte für das Kriterium vergeben hat, ist dieses Feld nicht vorhanden.
Diese Listen enthalten nur Einträge für die Kriterien, für die ein*e Lehrkraft entweder eine Stufe ausgewählt oder Punkte festgelegt hat. Wenn eine Lehrkraft beispielsweise bei der Benotung nur ein Kriterium berücksichtigt, enthalten draftRubricGrades und assignedRubricGrades nur ein Element, auch wenn die Benotungsskala viele Kriterien enthält.
Bewertungsschema löschen
Eine Benotungsskala kann mit einer standardmäßigen delete()-Anfrage gelöscht werden. Der folgende Code zeigt zur Vollständigkeit eine Beispielfunktion. Da die Benotung jedoch bereits begonnen hat, können Sie die aktuelle Benotungsskala nicht löschen:
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
).execute()
except HttpError as error:
print(f"An error occurred: {error}")
return error
Bewertungsraster exportieren und importieren
Bewertungsschemata können manuell in Google Tabellen exportiert werden, damit sie von Lehrkräften wiederverwendet werden können.
Sie können Bewertungskriterien nicht nur im Code angeben, sondern auch Bewertungsschemata aus diesen exportierten Tabellen erstellen und aktualisieren, indem Sie sourceSpreadsheetId anstelle von criteria im Bewertungsschema angeben:
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
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error