Eine rubric ist eine Vorlage, die Lehrkräfte bei der Benotung von Schüler-/Studentenarbeiten verwenden können. Mit der Classroom API können Sie diese Bewertungsraster im Namen des Lehrers verwalten.
Abbildung 1. Ansicht eines Beispielrubriks 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 eines Bewertungsschemas und darüber, wie die Benotung mit Bewertungsschemas über die Classroom-Benutzeroberfläche erfolgt.
Vorbereitung
In diesem Leitfaden wird davon ausgegangen, dass Sie Folgendes haben:
- Python 3.8.6 oder höher
- Paketverwaltungstool pip
- Ein Google Cloud-Projekt
- Ein Google Workspace for Education-Konto, in dem Google Classroom aktiviert ist.
- Einen Testkurs mit mindestens einem Test-Schüler-/Studentenkonto. Wenn Sie keine Classroom-Kurse 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 Anwendung 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 Preview-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.
Der Bereich classroom.coursework.students ermöglicht Lese- und Schreibzugriff auf Bewertungsraster (sowie Zugriff auf CourseWork). Der Bereich classroom.courses ermöglicht das Lesen und Schreiben von Kursen.
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. Eine Liste aller Classroom-Bereiche finden Sie unter OAuth 2.0-Bereiche für Google APIs. Die Rubriken werden hier nicht erwähnt, da die API noch in der Vorabversion ist.
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. Bewertungsraster können nur im Google Cloud-Projekt erstellt werden, in dem das übergeordnete CourseWork-Element erstellt wurde. Erstellen Sie für diesen Leitfaden 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 nun main.py, um die course_id der gerade erstellten Testklasse abzurufen. Erstellen Sie eine neue Beispielzuweisung 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. Ansicht einer Beispielaufgabe in Classroom.
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 Bewertungsschemata enthält. Dabei werden die ID-Eigenschaften für Kriterien und Stufen weggelassen, die bei der Erstellung 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,
# 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
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)
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 möglich. - Lehrkräfte können Kriterien und bewertete Stufen (jedoch nicht nicht bewertete Stufen) in der Benutzeroberfläche neu sortieren. Dadurch ändert sich ihre Reihenfolge in den Daten.
Weitere Informationen zur Struktur von Beurteilungsrastern finden Sie unter Einschränkungen.
Auf der Benutzeroberfläche sollten Sie das Bewertungsschema in der Aufgabe sehen.
Abbildung 3: Beispiel für ein Bewertungsschema für eine Classroom-Aufgabe
Bewertungsschema lesen
Bewertungsschemas können mit den Standardmethoden List und Get gelesen werden.
Jede Aufgabe kann höchstens ein Bewertungsschema enthalten. Daher mag List wenig intuitiv erscheinen, aber es ist hilfreich, wenn Sie noch keine Bewertungsschema-ID 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,
# 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
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,
# 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
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 Rubrik müssen Aktualisierungen mit einem Read-Modify-Write-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 Ebenen gilt als neue Reihenfolge in der UI (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',
# 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
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)
# 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: Ansicht des aktualisierten Bewertungsschemas.
Anhand von Bewertungsschema benotete Aufgaben ansehen
Derzeit können abgegebene Aufgaben noch nicht über die API mit einem Bewertungsschema benotet werden. Sie haben jedoch die Möglichkeit, über die Classroom-Benutzeroberfläche die mit einem Bewertungsschema benoteten Aufgaben zu lesen.
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
Abgegebene Aufgaben, die mit einem Bewertungsschema benotet wurden, haben zwei neue Eigenschaften: draftRubricGrades und assignedRubricGrades. Sie stehen für die Punkte und Stufen, die die Lehrkraft im Entwurf ausgewählt bzw. die Benotung festgelegt hat.
Außerdem enthalten Aufgaben von Schülern und Studenten mit einem zugehörigen Bewertungsschema das Feld rubricId, noch bevor sie benotet werden. Dies ist die aktuelle Benotungsskala, die mit der CourseWork verknüpft ist. Dieser Wert kann sich ändern, wenn Lehrkräfte eine Benotungsskala löschen und neu erstellen.
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 abgegebene Aufgaben von Schülern/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,
# 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
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 Kriterien für das Bewertungsschema. - Die
points, die die Lehrkraft für jedes Kriterium zugewiesen hat. Dies könnte von der ausgewählten Ebene stammen, aber die Lehrkraft könnte es auch überschrieben haben. - Die
levelIdder Stufe, die für jedes Kriterium ausgewählt wurde. 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
Ein Bewertungsschema kann über eine Standard-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,
# 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
Bewertungsraster exportieren und importieren
Bewertungsschemata können manuell in Google Tabellen exportiert werden, damit sie von Lehrkräften wiederverwendet werden können.
Neben den Bewertungsschemakriterien im Code können Sie Bewertungsschemas aus diesen exportierten Tabellenblättern erstellen und aktualisieren. Dazu geben Sie im Bewertungsschema-Text sourceSpreadsheetId anstelle von criteria an:
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
Feedback
Wenn Sie Probleme feststellen oder Verbesserungsvorschläge haben, teilen Sie uns dies bitte mit.