Benotungszeiträume mit der Classroom API verwalten

In diesem Leitfaden wird beschrieben, wie Sie die Endpunkte für die Benotungszeiträume in der Google Classroom API verwenden.

Übersicht

Benotungszeiträume werden erstellt, um Hausaufgaben, Tests und Projekte in bestimmten Zeiträumen zu organisieren. Mit der Classroom API können Entwickler im Namen von Administratoren und Lehrkräften Benotungszeiträume in Classroom erstellen, ändern und lesen. Sie können die Classroom API auch verwenden, um Benotungszeiträume für Kursaufgaben festzulegen.

Die Classroom API bietet zwei Endpunkte zum Lesen und Schreiben von Informationen zu Benotungszeiträumen in einem Kurs:

  • GetGradingPeriodSettings: Ermöglicht das Lesen der Einstellungen für den Benotungszeitraum in einem Kurs.
  • UpdateGradingPeriodSettings: Damit können Sie die Einstellungen für Benotungszeiträume in einem Kurs verwalten, indem Sie Benotungszeiträume hinzufügen, ändern und löschen und die konfigurierten Benotungszeiträume auf alle vorhandenen Kursaufgaben anwenden.

Lizenzierungs- und Teilnahmevoraussetzungen

Einstellungen für Benotungszeiträume in einem Kurs ändern

Damit Sie mithilfe des UpdateGradingPeriodSettings-Endpunkts Notenzeiträume in einem Kurs erstellen, ändern oder löschen können, müssen die folgenden Bedingungen erfüllt sein:

Benotungszeitraumeinstellungen in einem Kurs lesen

Domainadministratoren und Lehrkräfte eines Kurses können die Einstellungen für den Benotungszeitraum lesen, unabhängig davon, welche Lizenz ihnen zugewiesen ist. Das bedeutet, dass Anfragen an den Endpunkt GetGradingPeriodSettings im Namen eines beliebigen Domainadministrators oder einer beliebigen Lehrkraft zulässig sind.

Benotungszeitraum-ID für Kursaufgabe festlegen

Lehrkräfte eines Kurses können gradingPeriodId einfügen, wenn sie Kursaufgaben mit der API erstellen oder aktualisieren, unabhängig davon, welche Lizenz ihnen zugewiesen ist.

Prüfen, ob ein Nutzer Berechtigungen zum Einrichten von Benotungszeiträumen hat

Anfragen an den userProfiles.checkUserCapability-Endpunkt sind im Namen eines beliebigen Administrators oder einer beliebigen Lehrkraft zulässig. Hiermit wird festgelegt, ob der Nutzer Notenzeiträume ändern kann.

Vorbereitung

Dieser Leitfaden enthält Codebeispiele in Python und setzt Folgendes voraus:

  • Ein Google Cloud-Projekt. Eine Anleitung dazu finden Sie in der Python-Kurzanleitung.
  • Sie haben dem OAuth-Zustimmungsbildschirm Ihres Projekts die folgenden Bereiche hinzugefügt:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • Die ID eines Kurses, in dem die Benotungszeiträume geändert werden sollen. Der Kursinhaber muss eine Google Workspace for Education Plus-Lizenz haben.
  • Zugriff auf die Anmeldedaten einer Lehrkraft oder eines Administrators mit einer Google Workspace for Education Plus-Lizenz. Sie benötigen die Anmeldedaten eines Lehrers, um Kursaufgaben zu erstellen oder zu ändern. Administratoren können keine Kursaufgaben erstellen oder ändern, wenn sie nicht als Lehrkraft im Kurs eingetragen sind.

Ressource GradingPeriodSettings verwalten

Die Ressource GradingPeriodSettings enthält eine Liste einzelner GradingPeriods und ein boolesches Feld mit dem Namen applyToExistingCoursework.

Jedes einzelne GradingPeriods in der Liste muss die folgenden Anforderungen erfüllen:

  • Titel, Start- und Enddatum:Jeder Benotungszeitraum muss einen Titel, ein Start- und ein Enddatum haben.
  • Eindeutiger Titel:Jeder Benotungszeitraum muss einen eindeutigen Titel haben, der sich von allen anderen Benotungszeiträumen im Kurs unterscheidet.
  • Nicht überschneidende Daten:Die Start- und Enddaten jedes Benotungszeitraums dürfen sich nicht mit denen anderer Benotungszeiträume im Kurs überschneiden.
  • Chronologische Reihenfolge:Benotungszeiträume müssen anhand der Start- und Enddaten in chronologischer Reihenfolge aufgeführt werden.

Jeder Benotungszeitraum erhält bei der Erstellung eine von der Classroom API zugewiesene Kennung.

Der boolesche Wert applyToExistingCoursework ist eine dauerhafte Einstellung, mit der Sie zuvor erstellte CourseWork-Elemente in Benotungszeiträume einteilen können, ohne für jedes CourseWork-Element einen separaten API-Aufruf zum Ändern von gradingPeriodId ausführen zu müssen. Wenn der Wert auf True festgelegt ist, wird gradingPeriodId in Classroom automatisch für alle vorhandenen Kursaufgaben festgelegt, wenn courseWork.dueDate innerhalb des Start- und Enddatums eines vorhandenen Zeitraums für die Notenvergabe liegt. Wenn für die Kursarbeit kein Abgabetermin festgelegt wurde, verwendet Classroom courseWork.scheduledTime. Wenn keines der Felder vorhanden ist oder es keine Übereinstimmung mit dem Start- und Enddatum eines vorhandenen Bewertungszeitraums gibt, wird die CourseWork keinem Bewertungszeitraum zugeordnet.

Festlegen, ob ein Nutzer die Einstellungen für den Berichtszeitraum in einem Kurs ändern kann

Die Classroom API bietet den Endpunkt userProfiles.checkUserCapability, mit dem Sie proaktiv ermitteln können, ob ein Nutzer Anfragen an den Endpunkt UpdateGradingPeriodSettings senden kann.

Python

def check_grading_periods_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        capability = classroom_service.userProfiles().checkUserCapability(
          userId="me",
          capability="UPDATE_GRADING_PERIOD_SETTINGS",
           # Required while the checkUserCapability method is available in the Developer Preview Program.
          previewVersion="V1_20240930_PREVIEW"
        ).execute()

        # Retrieve the `allowed` boolean from the response.
        if capability.get("allowed"):
          print("User is allowed to update grading period settings in the course.")
        else:
          print("User is not allowed to update grading period settings in the course.")
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Benotungszeiträume hinzufügen

Nachdem Sie sich vergewissert haben, dass der Nutzer berechtigt ist, die Einstellungen für den Bewertungszeitraum in einem Kurs zu ändern, können Sie Anfragen an den UpdateGradingPeriodSettings-Endpunkt senden. Alle Änderungen an der GradingPeriodSettings-Ressource werden über den UpdateGradingPeriodSettings-Endpunkt vorgenommen, unabhängig davon, ob Sie einzelne Notenzeiträume hinzufügen, vorhandene Notenzeiträume ändern oder einen Notenzeitraum löschen.

Python

Im folgenden Beispiel wird die gradingPeriodSettings-Ressource so geändert, dass sie zwei Benotungszeiträume enthält. Der boolesche Wert applyToExistingCoursework ist auf True festgelegt. Dadurch wird der Wert gradingPeriodId für alle vorhandenen CourseWork-Elemente geändert, die zwischen dem Start- und Enddatum eines Bewertungszeitraums liegen. Hinweis: updateMask enthält beide Felder. Speichern Sie die IDs für die einzelnen Benotungszeiträume, sobald sie in der Antwort zurückgegeben werden. Sie müssen diese IDs verwenden, um die Benotungszeiträume bei Bedarf zu aktualisieren.

def create_grading_periods(classroom_service, course_id):
    """
    Create grading periods in a course and apply the grading periods
    to existing courseWork.
    """
    try:
        body = {
          "gradingPeriods": [
            {
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": True
        }
        gradingPeriodSettingsResponse = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body
        ).execute();

        print(f"Grading period settings updated.")
        return gradingPeriodSettingsResponse

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Einstellungen für Benotungszeiträume lesen

GradingPeriodSettings werden über den GetGradingPeriodSettings-Endpunkt gelesen. Alle Nutzer, unabhängig von der Lizenz, können die Einstellungen für die Benotungszeiträume in einem Kurs lesen.

Python

def get_grading_period_settings(classroom_service, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom_service.courses().getGradingPeriodSettings(
          courseId=course_id).execute()
        return gradingPeriodSettings
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Der Liste einen einzelnen Benotungszeitraum hinzufügen

Aktualisierungen eines einzelnen Benotungszeitraums müssen nach dem Muster „Lesen-Ändern-Schreiben“ erfolgen. Beachten Sie Folgendes:

  1. Lesen Sie die Liste der Benotungszeiträume in der GradingPeriodSettings-Ressource mit dem GetGradingPeriodSettings-Endpunkt.
  2. Nehmen Sie die gewünschten Änderungen an der Liste der Benotungszeiträume vor.
  3. Senden Sie die neue Liste der Benotungszeiträume in einer Anfrage an UpdateGradingPeriodSettings.

Mit diesem Muster können Sie dafür sorgen, dass die einzelnen Titel von Benotungszeiträumen in einem Kurs eindeutig sind und sich Start- und Enddatum von Benotungszeiträumen nicht überschneiden.

Beachten Sie die folgenden Regeln zum Aktualisieren der Liste der Benotungszeiträume:

  1. Benotungszeiträume, die ohne ID zur Liste hinzugefügt wurden, gelten als Ergänzungen.
  2. Bewertungszeiträume, die in der Liste fehlen, gelten als Löschungen.
  3. Zeiträume für die Notenvergabe mit einer vorhandenen ID, aber geänderten Daten werden als Bearbeitungen betrachtet. Unveränderte Attribute bleiben unverändert.
  4. Zeiträume mit neuen oder unbekannten IDs gelten als Fehler.

Python

Der folgende Code baut auf dem Beispiel in diesem Leitfaden auf. Ein neuer Zeitraum für die Noten wird mit dem Titel „Sommer“ erstellt. Der boolesche Wert applyToExistingCoursework ist im Anfragetext auf False gesetzt.

Dazu wird das aktuelle GradingPeriodSettings gelesen, der Liste wird ein neuer Bewertungszeitraum hinzugefügt und der boolesche Wert applyToExistingCoursework wird auf False gesetzt. Beachten Sie, dass alle Benotungszeiträume, die bereits auf vorhandene Kursaufgaben angewendet wurden, nicht entfernt werden. Im vorherigen Beispiel wurden die Notenzeiträume „Semester 1“ und „Semester 2“ bereits auf vorhandene Kursaufgaben angewendet und werden nicht aus Kursaufgaben entfernt, wenn applyToExistingCoursework in nachfolgenden Anfragen auf „False“ gesetzt ist.

def add_grading_period(classroom_service, course_id):
    """
    A new grading period is added to the list, but it is not applied to existing courseWork.
    """
    try:
        # Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
        # grading period IDs. You will need to include these IDs in the request
        # body to make sure existing grading periods aren't deleted.
        body = {
          "gradingPeriods": [
            {
              # Specify the ID to make sure the grading period is not deleted.
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              # Specify the ID to make sure the grading period is not deleted.
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            },
            {
              # Does not include an ID because this grading period is an addition.
              "title": "Summer",
              "start_date": {
                "day": 1,
                "month": 6,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 8,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": False
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Hilfreiche Hinweise zum booleschen Feld applyToExistingCoursework

Der boolesche Wert applyToExistingCoursework wird beibehalten. Wenn er also in einem vorherigen API-Aufruf auf True gesetzt und nicht geändert wurde, werden nachfolgende Aktualisierungen von Notenzeiträumen auf vorhandene CourseWork angewendet.

Wenn Sie diesen booleschen Wert in einer Anfrage an UpdateGradingPeriodSettings von True in False ändern, werden die neuen Änderungen, die Sie an GradingPeriodSettings vornehmen, nicht auf vorhandene CourseWork angewendet. Alle Informationen zum Benotungszeitraum, die in vorherigen API-Aufrufen auf Kursaufgaben angewendet wurden, als der boolesche Wert auf True gesetzt war, werden nicht entfernt. Diese boolesche Einstellung kann hilfreich sein, um vorhandene Kursaufgaben mit Ihren konfigurierten Benotungszeiträumen zu verknüpfen. Das Entfernen vorhandener Verknüpfungen zwischen Kursaufgaben und konfigurierten Benotungszeiträumen wird jedoch nicht unterstützt.

Wenn Sie den Titel eines Zeitraums für die Notenvergabe löschen oder ändern, werden diese Änderungen auf alle vorhandenen Kursaufgaben übertragen, unabhängig von der Einstellung des booleschen Werts applyToExistingCoursework.

auf alle Kursaufgaben übertragen.

Einzelnen Zeitraum in der Liste aktualisieren

Wenn Sie Daten ändern möchten, die mit einem vorhandenen Zeitraum für die Notenvergabe verknüpft sind, fügen Sie die ID des vorhandenen Zeitraums für die Notenvergabe in die Liste mit den geänderten Daten ein.

Python

In diesem Beispiel wird das Enddatum des Notenzeitraums „Sommer“ geändert. Das Feld applyToExistingCoursework wird auf True gesetzt. Wenn Sie diesen booleschen Wert auf True setzen, werden alle konfigurierten Bewertungszeiträume auf vorhandene Kursaufgaben angewendet. In der vorherigen API-Anfrage wurde der boolesche Wert auf False gesetzt, sodass der Notenzeitraum „Sommer“ nicht auf vorhandene Kursaufgaben angewendet wurde. Da dieses boolesche Feld jetzt auf True gesetzt ist, wird der Notenzeitraum „Sommer“ auf alle vorhandenen Kursaufgaben angewendet, die übereinstimmen.

def update_existing_grading_period(classroom_service, course_id):
    """
    An existing grading period is updated.
    """
    try:
        # Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
        # grading period IDs. You will need to include these IDs in the request
        # body to make sure existing grading periods aren't deleted.
        body = {
          "gradingPeriods": [
            {
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            },
            {
              # The end date for this grading period will be modified from August 31, 2024 to September 10, 2024.
              # Include the grading period ID in the request along with the new data.
              "id": "SUMMER_GRADING_PERIOD_ID",
              "title": "Summer",
              "start_date": {
                "day": 1,
                "month": 6,
                "year": 2024
              },
              "end_date": {
                "day": 10,
                "month": 9,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": True
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Einzelnen Benotungszeitraum löschen

Wenn Sie einen Benotungszeitraum löschen möchten, lassen Sie ihn in der Liste weg. Wenn ein Benotungszeitraum gelöscht wird, werden alle Verweise auf den Benotungszeitraum in CourseWork unabhängig von der Einstellung applyToExistingCoursework ebenfalls gelöscht.

Python

Wenn Sie das Beispiel in dieser Anleitung fortsetzen möchten, lassen Sie den Zeitraum „Sommer“ weg, um ihn zu löschen.

def delete_grading_period(classroom_service, course_id):
    """
    An existing grading period is deleted.
    """
    try:
        body = {
          "gradingPeriods": [
            {
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            }
          ]
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Das Feld gradingPeriodId in CourseWork verwalten

Die Ressource „CourseWork“ enthält das Feld gradingPeriodId. Sie können die CourseWork-Endpunkte verwenden, um den mit einer CourseWork verknüpften Zeitraum für die Notenvergabe zu lesen und zu schreiben. Es gibt drei Möglichkeiten, diese Verknüpfung zu verwalten:

  • automatische Zuordnung von Benotungszeiträumen basierend auf dem Datum
  • benutzerdefinierter zugehöriger Benotungszeitraum
  • Keine Zuordnung zum Benotungszeitraum

1. Datumsbasierte Zuordnung von Benotungszeiträumen

Wenn Sie Kursaufgaben erstellen, können Sie die Zuordnung zum Notenzeitraum von Classroom übernehmen lassen. Lassen Sie dazu das Feld gradingPeriodId in der CourseWork-Anfrage weg. Geben Sie dann die Felder dueDate oder scheduledTime in der CourseWork-Anfrage an. Wenn das dueDate in einen vorhandenen Benotungszeitraum fällt, wird die ID dieses Benotungszeitraums in Classroom für die Kursaufgabe festgelegt. Wenn das Feld dueDate nicht angegeben ist, wird gradingPeriodId in Classroom anhand des Felds scheduledTime bestimmt. Wenn keines der Felder angegeben ist oder kein Zeitraum für die Benotung gefunden wird, wird für die CourseWork kein gradingPeriodId festgelegt.

2. Benutzerdefinierter zugehöriger Benotungszeitraum

Wenn Sie die CourseWork einem anderen Zeitraum für die Notenvergabe zuordnen möchten als dem, der mit dueDate oder scheduledTime übereinstimmt, können Sie das Feld gradingPeriodId beim Erstellen oder Aktualisieren von CourseWork manuell festlegen. Wenn Sie die gradingPeriodId manuell festlegen, wird die automatische datumsbasierte Zuordnung von Benotungszeiträumen in Classroom nicht ausgeführt.

3. Keine Zuordnung zum Benotungszeitraum

Wenn die CourseWork nicht mit einem Zeitraum für die Notenvergabe verknüpft werden soll, legen Sie das Feld gradingPeriodId in der CourseWork-Anfrage auf einen leeren String fest (gradingPeriodId: "").

Wenn Sie die Programmiersprache Go verwenden und keinen Zeitraum für die Benotung festlegen möchten, sollten Sie das Feld ForceSendFields auch in den Anfragetext aufnehmen. In der Go-Clientbibliothek werden Standardwerte in API-Anfragen aufgrund des Feld-Tags omitempty für alle Felder weggelassen. Mit dem Feld ForceSendFields wird dies umgangen und der leere String wird gesendet, um anzugeben, dass für diese Kursarbeit kein Benotungszeitraum festgelegt werden soll. Weitere Informationen finden Sie in der Dokumentation zur Go-Clientbibliothek für Google APIs.

Ok

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"GradingPeriodId"},
}

Was passiert mit der ID des Bewertungszeitraums, wenn das Fälligkeitsdatum aktualisiert wird?

Wenn Sie das Feld dueDate von CourseWork aktualisieren und eine benutzerdefinierte oder keine Zuordnung des Zeitraums für die Benotung beibehalten möchten, sollten Sie dueDate und gradingPeriodId in „updateMask“ und im Anfragetext angeben. So wird verhindert, dass in Classroom die gradingPeriodId mit dem Notenzeitraum überschrieben wird, der dem neuen dueDate entspricht.

Python

body = {
  "dueDate": {
    "month": 6,
    "day": 10,
    "year": 2024
  },
  "dueTime": {
    "hours": 7
  },
  "gradingPeriodId": "<INSERT-GRADING-PERIOD-ID-OR-EMPTY-STRING>"
}
courseWork = classroom_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()
Zurück
Noten festlegen und aktualisieren
Weiter
Beschränkungen