Eine rubric ist eine Vorlage, mit der Lehrkräfte Aufgaben benoten können. Über die Classroom API können Sie im Namen der Lehrkraft diese Bewertungsschemas verwalten.
Abbildung 1. Beispielrubrik für eine Classroom-Aufgabe ansehen
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 die Benotung von Bewertungsschemas in der Classroom-Benutzeroberfläche.
Voraussetzungen
In diesem Leitfaden wird Folgendes vorausgesetzt:
- Python 3.8.6 oder höher
- Das Paketverwaltungstool pip
- Ein Google Cloud-Projekt
- Ein Google Workspace for Education-Konto, bei dem Google Classroom aktiviert ist.
- Ein Testkurs mit mindestens einem Studentenkonto für die Prüfung. Wenn Sie keinen Classroom-Kurs haben, den Sie zum Testen verwenden können, erstellen Sie einen Kurs in der UI und fügen Sie einen Schüler/Studenten 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 GCP-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: „Vorschau-Client für Bewertungsschemas“.
- Klicken Sie auf Erstellen. Der Bildschirm „OAuth-Client erstellt“ wird mit der neuen Client-ID und dem neuen Clientschlüssel angezeigt.
- 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 erstellen.
OAuth-Bereiche konfigurieren
Abhängig von den 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 zum Bildschirm „Bereiche“ zu gelangen.
- 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 Bewertungsschemas sowie den Zugriff auf CourseWork. Der Bereich classroom.courses ermöglicht Lese- und Schreibkurse.
Die für eine bestimmte Methode erforderlichen Bereiche sind in der Referenzdokumentation für die Methode aufgeführt. Ein Beispiel finden Sie unter courses.courseWork.rubrics.create-Autorisierungsbereiche. Sie finden alle Classroom-Bereiche in OAuth 2.0-Bereiche für Google APIs. Bewertungsschemas werden hier nicht erwähnt, da sich die API noch in der Vorschau befindet.
Beispiel konfigurieren
Installieren Sie in Ihrem Arbeitsverzeichnis die Google-Clientbibliothek für Python:
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
Erstellen Sie eine Datei mit dem Namen main.py, mit der die Clientbibliothek erstellt und der Nutzer autorisiert wird. Verwenden Sie dazu 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 Skript mit python main.py aus. Sie sollten aufgefordert werden, sich anzumelden und OAuth-Bereiche zuzustimmen.
Aufgabe erstellen
Ein Bewertungsschema ist mit einer Aufgabe oder CourseWork verknüpft und ist nur im Kontext dieser CourseWork sinnvoll. Bewertungsschemas können nur von dem Google Cloud-Projekt erstellt werden, in dem das übergeordnete CourseWork-Element erstellt wurde. Erstellen Sie für diese Anleitung eine neue CourseWork-Zuweisung mit einem Skript.
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 course_id und coursework_id. Diese sind für alle CRUD-Vorgänge für Bewertungsschemas erforderlich.
Sie sollten jetzt eine Beispiel-CourseWork in Classroom haben.
Abbildung 2. Ansicht einer Beispielaufgabe in Classroom
Bewertungsschema erstellen
Jetzt können Sie mit der Verwaltung von Bewertungsschemas beginnen.
Ein Bewertungsschema kann in einem CourseWork mit einem Create-Aufruf erstellt werden, der das vollständige Bewertungsschema enthält. Dabei werden die ID-Eigenschaften für Kriterien und Ebenen weggelassen (sie werden bei der Erstellung generiert).
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 das Beispielrubrik mithilfe Ihrer IDs Course
und CourseWork aus früheren Versionen 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 des Bewertungsschemas:
- Die Reihenfolge von Kriterium und Leveln wird in der Classroom-Benutzeroberfläche übernommen.
- Bewertete Ebenen (mit dem Attribut
points) müssen nach Punkten in aufsteigender oder absteigender Reihenfolge sortiert werden. Sie können nicht nach dem Zufallsprinzip sortiert werden. - Lehrkräfte können Kriterien und bewertete Stufen (aber keine nicht bewerteten Stufen) in der Benutzeroberfläche neu sortieren, wodurch sich ihre Reihenfolge in den Daten ändert.
Weitere Informationen zur Struktur von Bewertungsschemas finden Sie unter Einschränkungen.
In der Benutzeroberfläche sollte nun das Bewertungsschema in der Aufgabe zu sehen sein.
Abbildung 3: Beispielrubrik für eine Classroom-Aufgabe ansehen
Bewertungsschema lesen
Bewertungsschemas können mit den Standardmethoden List und Get gelesen werden.
Eine Aufgabe kann höchstens ein Bewertungsschema enthalten, sodass List wenig intuitiv erscheint. Es ist jedoch hilfreich, wenn Sie die Bewertungsschema-ID noch nicht haben. Wenn kein Bewertungsschema mit einem CourseWork verknüpft ist, ist die Antwort List 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 Sie den Befehl main.py und führen Sie ihn aus, um das von Ihnen 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 die Eigenschaft id im Bewertungsschema für spätere Schritte.
Get funktioniert gut, wenn Sie die Bewertungsschema-ID haben. Die Verwendung von Get in der Funktion könnte stattdessen 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
Diese Implementierung gibt den Fehler 404 zurück, wenn kein Bewertungsschema vorhanden ist.
Bewertungsschema aktualisieren
Aktualisierungen eines Bewertungsschemas erfolgen in Patch-Anrufen. Aufgrund der komplexen Struktur eines Bewertungsschemas müssen Aktualisierungen mit einem Read-Modify-Write-Muster (Lesen-Ändern-Schreiben) erfolgen, bei dem das gesamte Attribut criteria ersetzt wird.
Die Aktualisierungsregeln lauten wie folgt:
- Kriterien oder Ebenen, die ohne ID hinzugefügt wurden, gelten als Ergänzungen.
- Kriterien oder Stufen, die davor fehlen, gelten als Löschungen.
- Kriterien oder Ebenen mit einer vorhandenen ID, aber geänderten Daten werden als Änderungen betrachtet. Unveränderte Eigenschaften bleiben unverändert.
- Kriterien oder Ebenen, die mit einer neuen oder unbekannten ID angegeben werden, gelten als Fehler.
- Die Reihenfolge der neuen Kriterien und Ebenen wird als neue UI-Reihenfolge 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',
# 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 zur Änderung mit einem updateMask 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 übernommen werden.
Abbildung 4: Ansicht des aktualisierten Bewertungsschemas.
Nach Bewertungsschema benotete Aufgaben ansehen
Aktuell können abgegebene Aufgaben von der API nicht mithilfe eines Bewertungsschemas benotet werden. Sie können jedoch in der Classroom-Benutzeroberfläche die Noten von Schülern oder Studenten lesen, die mit einem Bewertungsschema benotet wurden.
Arbeiten Sie als Schüler oder Student in der Classroom-Benutzeroberfläche die Beispielaufgabe ab und geben Sie sie ab. Als Lehrkraft können Sie dann die Aufgabe anhand des Bewertungsschemas manuell benoten.
Abbildung 5: Ansicht des Bewertungsschemas während der Benotung durch Lehrkräfte.
Abgegebene Aufgaben von Schülern, die mit einem Bewertungsschema benotet wurden, haben zwei neue Eigenschaften: draftRubricGrades und assignedRubricGrades. Diese repräsentieren die Punkte und Stufen, die die Lehrkraft während des Entwurfs ausgewählt hat, bzw. die zugewiesene Benotungsstatus.
Außerdem enthalten abgegebene Aufgaben mit einem zugehörigen Bewertungsschema bereits vor der Benotung das Feld rubricId. Es stellt das neueste Bewertungsschema dar, das mit CourseWork verknüpft ist. Dieser Wert kann sich ändern, wenn die Lehrkräfte ein Bewertungsschema löschen und neu erstellen.
Sie können die vorhandenen Methoden studentSubmissions.Get und studentSubmissions.List verwenden, um benotete Einreichungen anzusehen.
Fügen Sie main.py die folgende Funktion hinzu, um die abgegebenen Aufgaben der Schüler oder 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 den Befehl main.py und führen Sie ihn aus, um die Noten für die Abgabe anzusehen.
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:
- Die
criterionIdder entsprechenden Bewertungsschemakriterien. - Die
points, die die Lehrkraft jedem Kriterium zugewiesen hat. Diese kann von der ausgewählten Stufe stammen, aber auch von der Lehrkraft hätte sie überschrieben werden können. - Die
levelIdder für jedes Kriterium ausgewählten Ebene. Wenn die Lehrkraft keine Stufe ausgewählt, aber dennoch Punkte für das Kriterium zugewiesen hat, ist dieses Feld nicht vorhanden.
Diese Listen enthalten nur Einträge für die Kriterien, nach denen die Lehrkraft entweder eine Stufe oder Vorgaben ausgewählt hat. Wenn eine Lehrkraft beispielsweise bei der Benotung nur mit einem Kriterium interagiert, wird für draftRubricGrades und assignedRubricGrades nur ein Element angezeigt, auch wenn das Bewertungsschema viele Kriterien enthält.
Bewertungsschema löschen
Ein Bewertungsschema kann mit einer standardmäßigen Delete-Anfrage gelöscht werden. Der folgende Code zeigt eine Beispielfunktion der Vollständigkeit. Da die Benotung jedoch bereits begonnen hat, kann das aktuelle Bewertungsschema nicht gelöscht werden:
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
Bewertungsschemas exportieren und importieren
Bewertungsschemas können manuell in Google Tabellen exportiert werden, damit sie von den Lehrkräften wiederverwendet werden können.
Sie können Bewertungsschemakriterien nicht nur im Code, sondern auch aus diesen exportierten Tabellenblättern erstellen und aktualisieren. Geben Sie dazu sourceSpreadsheetId im Bewertungsschema 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 auf Probleme stoßen oder Feedback geben möchten, senden Sie uns Feedback.