Erste Schritte mit Bewertungsschemas

Ein rubric ist eine Vorlage, die Lehrkräfte beim Benoten von Schülern/Studenten verwenden können Einreichungen. Mit der Classroom API können Sie im Namen des um diese Bewertungsschemata zu 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. Weitere Informationen finden Sie unter in diesen Hilfeartikeln zu den allgemeinen Informationen Struktur eines Bewertungsschemas und wie das Bewertungsschema Die Benotung erfolgt über die Classroom-Benutzeroberfläche.

Vorbereitung

In diesem Leitfaden wird davon ausgegangen, dass Sie über Folgendes verfügen:

• Python 3.8.6 oder höher
• Paketverwaltungstool pip
• Ein Google Cloud-Projekt
• Ein Google Workspace for Education-Konto bei Google Classroom aktiviert sein.
• Ein Testkurs mit mindestens einem Test-Schülerkonto. Wenn Sie kein Classroom-Kurs, den Sie zum Testen nutzen können, erstellen Sie eines in der Benutzeroberfläche und Fügen Sie einen Testteilnehmer 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 läuft, müssen Sie für jede Plattform eine separate Client-ID erstellen.

1. Gehen Sie zur Google Cloud-Seite Anmeldedaten im Google Cloud Console
2. Klicken Sie auf Anmeldedaten erstellen. OAuth-Client-ID.
3. Klicken Sie auf Anwendungstyp > Desktop-App:
4. Geben Sie in das Feld Name einen Namen für die Anmeldedaten ein. Dieser Name ist nur in der Google Cloud Console angezeigt. Beispiel: „Client für Bewertungsschemas“.
5. Klicken Sie auf Erstellen. Der Bildschirm "OAuth-Client erstellt" wird angezeigt. Client-ID und Clientschlüssel.
6. Klicken Sie auf JSON herunterladen und dann auf OK. Die neu erstellten Anmeldedaten wird unter OAuth 2.0-Client-IDs angezeigt.
7. Speichern Sie die heruntergeladene JSON-Datei als credentials.json und verschieben Sie sie nach in Ihrem Arbeitsverzeichnis.
8. 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.

1. Rufen Sie den OAuth-Zustimmungsbildschirm auf.
2. Klicken Sie auf App bearbeiten > Speichern und fortfahren, um den Bildschirm „Bereiche“ aufzurufen.
3. Klicken Sie auf Bereiche hinzufügen oder entfernen.
4. Fügen Sie die folgenden Bereiche hinzu, falls noch nicht geschehen: <ph type="x-smartling-placeholder">
   </ph>
   • https://www.googleapis.com/auth/classroom.coursework.students
   • https://www.googleapis.com/auth/classroom.courses
5. Klicken Sie dann auf Aktualisieren > Speichern und fortfahren > Speichern und fortfahren > Zurück zum Dashboard.

Weitere Informationen finden Sie unter OAuth-Zustimmungsbildschirm konfigurieren. mehr.

Der Bereich classroom.coursework.students ermöglicht Lese- und Schreibzugriff auf Bewertungsschemas (mit dem Zugriff auf CourseWork) und dem Bereich classroom.courses Lese- und Schreibkurse.

Die für eine bestimmte Methode erforderlichen Bereiche sind in der Referenzdokumentation aufgeführt. für die Methode. Siehe courses.courseWork.rubrics.create-Autorisierungsbereiche als Beispiel. Eine Liste aller Classroom-Bereiche finden Sie unter 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 die mit Ihrem 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-Umfänge.

Aufgabe erstellen

Ein Bewertungsschema ist mit einer Aufgabe oder CourseWork verknüpft und ist im Kontext von CourseWork sinnvoll ist. Bewertungsschemas können nur von Das Google Cloud-Projekt, in dem das übergeordnete Element CourseWork erstellt wurde. Für die Zwecke, dieser Anleitung, erstellen Sie eine neue CourseWork-Aufgabe 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 jetzt main.py, um die course_id der gerade durchgeführten Testklasse abzurufen. erstellt, eine neue Beispielaufgabe erstellen und die 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.

Speichern Sie course_id und coursework_id. Diese sind für alle Bewertungsschemas (CRUD) erforderlich Geschäftsabläufe.

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 auf einem CourseWork mit einem Create-Aufruf erstellt werden, der Folgendes enthält: Vollständiges Bewertungsschema-Objekt, wobei die ID-Eigenschaften für Kriterien und Stufen weggelassen werden Diese 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 mithilfe der Course das Beispiel-Bewertungsschema zu erstellen. und CourseWork-IDs von vorhin:

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 Kriterien und Stufen wird in der Classroom-Benutzeroberfläche widergespiegelt.
• Bewertete Level (mit der Eigenschaft points) müssen nach Punkten sortiert werden in aufsteigender oder absteigender Reihenfolge (nicht nach dem Zufallsprinzip sortiert)
• Lehrkräfte können Kriterien und Punktzahlen neu sortieren. Ebenen) in der Benutzeroberfläche. Dadurch ändert sich ihre Reihenfolge in den Daten.

Weitere Hinweise zur Struktur von Bewertungsschemas finden Sie unter Einschränkungen.

Auf der Benutzeroberfläche sollten Sie das Bewertungsschema in der Aufgabe sehen.

Abbildung 3: Ansicht eines Beispielrubriks 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. Deshalb sieht es aus, als ob List nicht intuitiv, aber hilfreich, wenn Sie noch keine Bewertungsschema-ID haben. Wenn es keinem Bewertungsschema zugeordnet ist, das 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 main.py und führen Sie den Befehl 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 im Bewertungsschema die Property id für spätere Schritte.

Get funktioniert gut, wenn Sie die Bewertungsschema-ID haben. Get in der Funktion verwenden kann 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 einen 404-Fehler zurück, wenn kein Bewertungsschema vorhanden ist.

Bewertungsschema aktualisieren

Die Aktualisierung eines Bewertungsschemas erfolgt über Patch-Aufrufe. Aufgrund der komplexen Struktur eines Bewertungsschemas müssen Aktualisierungen mit einem Read-Change-Write-Muster erfolgen, wobei das Lesen-Ändern-Schreiben-Muster gesamte criteria-Eigenschaft wird ersetzt.

Es gelten die folgenden Aktualisierungsregeln:

1. Kriterien oder Ebenen, die ohne ID hinzugefügt wurden, werden berücksichtigt Ergänzungen.
2. Kriterien oder Ebenen, die vorher fehlen, werden berücksichtigt Löschungen.
3. Kriterien oder Ebenen mit einer vorhandenen ID, aber geänderten Daten werden berücksichtigt edits: Unveränderte Properties bleiben unverändert.
4. Kriterien oder Ebenen, die mit neuen oder unbekannten IDs bereitgestellt werden, werden berücksichtigt. errors zurückgegeben wird.
5. Die Reihenfolge der neuen Kriterien und Ebenen wird als neue Reihenfolge in der Benutzeroberfläche betrachtet. (unter Berücksichtigung der 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

Ändern Sie dann main.py, um für jedes der oben genannten Updates eine Änderung vorzunehmen. Regeln:

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.

Abgegebene Aufgaben ansehen, die mit Bewertungsschemas benotet wurden

Derzeit können abgegebene Aufgaben von der API nicht mit einem Bewertungsschema benotet werden. Sie können die Noten von Bewertungsschemas für Aufgaben lesen, die mit einem Bewertungsschema benotet wurden. über die Classroom-Benutzeroberfläche.

Bearbeiten Sie als Schüler oder Student über die Classroom-Benutzeroberfläche Ihre Beispielaufgabe und geben Sie sie ab. Anschließend können Sie als Lehrkraft die Aufgabe manuell mit dem Bewertungsschema benoten.

Abbildung 5: Lehrkräfte sehen das Bewertungsschema während der Benotung.

Abgegebene Aufgaben, die anhand eines Bewertungsschemas benotet wurden, erhalten zwei neue draftRubricGrades und assignedRubricGrades, die die Punkte und Stufen, die von der Lehrkraft beim Entwurf und bei der Benotung ausgewählt wurden Bundesländer.

Außerdem enthalten Aufgaben von Schülern/Studenten mit einem zugehörigen Bewertungsschema das Zeichen rubricId. bereits vor der Benotung. Dies entspricht dem letzten Bewertungsschema, das mit CourseWork. Dieser Wert kann sich ändern, wenn Lehrkräfte ein Bewertungsschemata.

Sie können die vorhandenen studentSubmissions.Get- und studentSubmissions.List-Methoden, um benotete Aufgaben anzusehen.

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 sich die Noten der abgegebenen Aufgabe 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 Folgendes:

• Die criterionId der entsprechenden Bewertungsschemakriterien.
• Die points, die die Lehrkraft jedem Kriterium zugewiesen hat. Dies könnte aus der Stufe ausgewählt, aber die Lehrkraft könnte dies ebenfalls überschrieben haben.
• Die levelId der Stufe, die für jedes Kriterium ausgewählt wurde. Wenn die Lehrkraft die eine Stufe auswählen, dem Kriterium aber dennoch Punkte zugewiesen haben, nicht vorhanden ist.

Diese Listen enthalten nur Einträge für die Kriterien, nach denen eine Lehrkraft entweder Level oder Sollwerte ausgewählt haben. Wenn eine Lehrkraft beispielsweise nur bei der Benotung mit einem Kriterium interagieren: draftRubricGrades und „assignedRubricGrades“ hätte nur ein Element, auch wenn das Bewertungsschema viele Kriterien.

Bewertungsschema löschen

Ein Bewertungsschema kann über eine Standard-Delete-Anfrage gelöscht werden. Der folgende Code zeigt eine Beispielfunktion der Vollständigkeit. Da die Benotung jedoch bereits begonnen hat, können Sie das aktuelle Bewertungsschema 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

Bewertungsschemas exportieren und importieren

Bewertungsschemas können manuell in Google exportiert werden Tabellen, die von Lehrkräften wiederverwendet werden können.

Neben der Angabe von Kriterien für Bewertungsschemas im Code können Sie auch aktualisieren Sie Bewertungsschemas aus diesen exportierten Tabellen, indem Sie die sourceSpreadsheetId im Bewertungsschematext statt 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

Feedback

Wenn Sie Probleme feststellen oder sich etwas mitteilen möchten, geben Sie uns bitte Feedback.