Benotungszeiträume mit der Classroom API verwalten

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

Überblick

Benotungszeiträume werden erstellt, um Hausaufgaben, Quizze und Projekte in bestimmte Zeiträume zu unterteilen. 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 auch die Classroom API verwenden, um Benotungszeiträume für KursWork festzulegen.

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

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

Lizenzierungsanforderungen

Einstellungen für den Benotungszeitraum in einem Kurs ändern

Wenn Sie Benotungszeiträume in einem Kurs mit dem Endpunkt UpdateGradingPeriodSettings erstellen, ändern oder löschen möchten, müssen die folgenden Bedingungen erfüllt sein:

Einstellungen für den Benotungszeitraum in einem Kurs lesen

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

Benotungszeitraum-ID in CourseWork festlegen

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

Berechtigung eines Nutzers zum Einrichten von Benotungszeiträumen prüfen

Anfragen an den Endpunkt checkGradingPeriodsSetupEligibility sind im Namen eines Administrators oder einer Lehrkraft zulässig. Damit legen Sie fest, ob der Nutzer die Benotungszeiträume in einem Kurs ändern kann.

Voraussetzungen

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

  • Ein Google Cloud-Projekt. Sie können sie anhand der Anleitung im Python-Schnellstart einrichten.
  • Dem OAuth-Zustimmungsbildschirm Ihres Projekts wurden die folgenden Bereiche hinzugefügt:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • Eine ID eines Kurses, in der 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 einer Lehrkraft, um Kursarbeiten zu erstellen oder zu ändern. Administratoren können CourseWork nur erstellen oder ändern, wenn sie eine Lehrkraft des Kurses sind.

GradingPeriodSettings-Ressource verwalten

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

Die Liste GradingPeriods enthält alle einzelnen Benotungszeiträume in einem Kurs. Sie müssen für jeden Benotungszeitraum in der Liste einen Titel, ein Startdatum und ein Enddatum angeben. Jeder Benotungszeitraum in einem Kurs muss einen eindeutigen Titel haben und die Start- und Enddaten der verschiedenen Benotungszeiträume dürfen sich nicht überschneiden. Jeder Benotungszeitraum hat eine eigene, der Classroom API zugewiesene Kennung.

Der boolesche Wert applyToExistingCoursework ist eine dauerhafte Einstellung, mit der Sie zuvor erstellte CourseWork in Benotungszeiträumen organisieren können, ohne einen separaten API-Aufruf ausführen zu müssen, um die gradingPeriodId für jede CourseWork zu ändern. Wenn die Richtlinie auf True gesetzt ist, legt Classroom automatisch gradingPeriodId für alle vorhandenen KursWork fest, wenn die courseWork.dueDate in das Start- und Enddatum eines vorhandenen Benotungszeitraums fällt. Wenn für die Kursaufgabe kein Abgabetermin festgelegt wurde, wird in Classroom die courseWork.scheduledTime verwendet. Wenn keines der Felder vorhanden ist oder es innerhalb des Start- und Enddatums eines vorhandenen Benotungszeitraums keine Übereinstimmung gibt, wird die Kursaufgabe mit keinem Benotungszeitraum verknüpft.

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

Da Benotungszeiträume in Classroom nur für Nutzer mit einer bestimmten Lizenz erstellt und geändert werden können, stellt die Classroom API den Endpunkt checkGradingPeriodsSetupEligibility bereit, mit dem Sie proaktiv feststellen können, ob ein Nutzer Anfragen an den Endpunkt UpdateGradingPeriodSettings senden kann.

Python

def check_grading_period_setup_eligibility(classroom, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        grading_period_eligibility_response = classroom.courses().checkGradingPeriodsSetupEligibility(
          courseId=course_id, previewVersion="V1_20240401_PREVIEW").execute()

        # Retrieve the isGradingPeriodsSetupEligible boolean from the response.
        # If the boolean is `True`, the user is able to modify grading period settings in the course.
        is_grading_periods_eligible = grading_period_eligibility_response.get("isGradingPeriodsSetupEligible")
        return is_grading_periods_eligible
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Benotungszeiträume hinzufügen

Da Sie nun sicher sind, dass der Nutzer die erforderliche Lizenz hat, um die Einstellungen für den Benotungszeitraum in einem Kurs zu ändern, können Sie Anfragen an den Endpunkt UpdateGradingPeriodSettings senden. Änderungen an der Ressource GradingPeriodSettings werden mit dem Endpunkt UpdateGradingPeriodSettings vorgenommen, unabhängig davon, ob Sie einzelne Benotungszeiträume hinzufügen, vorhandene Benotungszeiträume ändern oder einen Benotungszeitraum löschen.

Python

Im folgenden Beispiel wird die Ressource gradingPeriodSettings so geändert, dass sie zwei Benotungszeiträume enthält. Der boolesche Wert applyToExistingCoursework ist auf True gesetzt. Dadurch wird die gradingPeriodId für alle vorhandenen CourseWork-Elemente geändert, die zwischen dem Start- und Enddatum eines Benotungszeitraums liegen. 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 bei Bedarf verwenden, um die Benotungszeiträume zu aktualisieren.

def create_grading_periods(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body,
          previewVersion="V1_20240401_PREVIEW"
        ).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 den Benotungszeitraum lesen

GradingPeriodSettings werden mit dem Endpunkt GetGradingPeriodSettings gelesen. Jeder Nutzer kann unabhängig von seiner Lizenz die Einstellungen für Benotungszeiträume in einem Kurs lesen.

Python

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

Einzelnen Benotungszeitraum der Liste 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 Ressource GradingPeriodSettings mit dem Endpunkt GetGradingPeriodSettings.
  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 Titel der einzelnen Benotungszeiträume in einem Kurs unterschiedlich sind und sich die Start- und Enddaten von Benotungszeiträumen nicht überschneiden.

Beachten Sie beim Aktualisieren der Liste mit Benotungszeiträumen die folgenden Regeln:

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

Python

Der folgende Code baut auf dem Beispiel in diesem Leitfaden auf. Es wird ein neuer Benotungszeitraum mit dem Titel „Summer“ erstellt. Der boolesche Wert applyToExistingCoursework wird im Anfragetext auf False gesetzt.

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

def add_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
          previewVersion="V1_20240401_PREVIEW").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

Beachten Sie, dass der boolesche Wert applyToExistingCoursework persistent bleibt. Wenn der boolesche Wert bei einem vorherigen API-Aufruf auf True gesetzt und nicht geändert wurde, werden nachfolgende Aktualisierungen der Benotungszeiträume auf vorhandene KursWork angewendet.

Hinweis: Wenn du diesen booleschen Wert in einer Anfrage von True in False in UpdateGradingPeriodSettings änderst, werden nur die neuen Änderungen, die du an GradingPeriodSettings vornimmst, nicht auf vorhandene CourseWork angewendet. Informationen zum Benotungszeitraum, die in früheren API-Aufrufen auf CourseWork angewendet wurden, als der boolesche Wert auf True festgelegt war, werden nicht entfernt. Sie können sich diese boolesche Einstellung so vorstellen, dass sie die Verknüpfung von KursWork mit Ihren konfigurierten Benotungszeiträumen unterstützt, das Entfernen bestehender Verknüpfungen zwischen CourseWork und konfigurierten Benotungszeiträumen jedoch nicht.

Wenn Sie einen Benotungszeitraum löschen oder ändern, werden diese Änderungen unabhängig von der Einstellung des booleschen Werts applyToExistingCoursework auf alle vorhandenen KursArbeiten angewendet.

Einzelne Benotungszeiträume in der Liste aktualisieren

Wenn Sie Daten ändern möchten, die mit einem vorhandenen Benotungszeitraum verknüpft sind, nehmen Sie die ID des vorhandenen Benotungszeitraums in die Liste mit den geänderten Daten auf.

Python

In diesem Beispiel wird das Enddatum des Benotungszeitraums „Sommer“ geändert. Das Feld „applyToExistingCoursework“ wird auf „True“ gesetzt. Wenn Sie diesen booleschen Wert auf True festlegen, werden alle konfigurierten Benotungszeiträume auf vorhandene KursWork angewendet. In der vorherigen API-Anfrage wurde der boolesche Wert auf False festgelegt, sodass der Benotungszeitraum „Summer“ nicht auf vorhandene KursWork angewendet wurde. Da dieses boolesche Feld jetzt auf True gesetzt ist, wird der Benotungszeitraum „Summer“ auf alle entsprechenden vorhandenen KursWork angewendet.

def update_existing_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
          previewVersion="V1_20240401_PREVIEW").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 aus der Liste weg. Hinweis: Wenn ein Benotungszeitraum gelöscht wird, werden auch alle Verweise auf den Benotungszeitraum in CourseWork gelöscht, unabhängig von der Einstellung applyToExistingCoursework.

Python

Wenn Sie das Beispiel in diesem Leitfaden fortsetzen möchten, lassen Sie den Benotungszeitraum „Sommer“ weg, um ihn zu löschen.

def delete_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods',
          previewVersion="V1_20240401_PREVIEW").execute()
        return gradingPeriodSettings

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

Feld gradingPeriodId in CourseWork verwalten

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

  • automatische Verknüpfung mit datumsbasierten Benotungszeiträumen
  • benutzerdefinierter verknüpfter Benotungszeitraum
  • Keine Verknüpfung mit dem Benotungszeitraum

1. Verknüpfung mit datumsbasiertem Benotungszeitraum

Beim Erstellen von CourseWork können Sie zulassen, dass Classroom die Verknüpfung des Benotungszeitraums für Sie übernimmt. Lassen Sie dazu das Feld gradingPeriodId in der CourseWork-Anfrage weg. Geben Sie dann in der KursWork-Anfrage das Feld dueDate oder scheduledTime an. Wenn dueDate in einen vorhandenen Zeitraum für den Benotungszeitraum fällt, legt Classroom diese Benotungszeitraum-ID für KursWork fest. Wenn das Feld dueDate nicht angegeben ist, bestimmt Classroom den gradingPeriodId basierend auf dem Feld scheduledTime. Wenn keines der beiden Felder angegeben ist oder es keine Übereinstimmung mit dem Zeitraum des Benotungszeitraums gibt, wird für KursWork keine gradingPeriodId festgelegt.

2. Benutzerdefinierter verknüpfter Benotungszeitraum

Wenn Sie KursWork mit einem anderen Benotungszeitraum verknüpfen 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 gradingPeriodId manuell festlegen, wird die automatische datumsbasierte Benotungszeit in Classroom nicht verknüpft.

3. Keine Verknüpfung mit dem Benotungszeitraum

Wenn Sie nicht möchten, dass KursWork mit einem Benotungszeitraum verknüpft wird, setzen Sie das Feld gradingPeriodId in der CourseWork-Anfrage auf einen leeren String (gradingPeriodId: "").

Was passiert mit der ID des Benotungszeitraums, wenn der Abgabetermin aktualisiert wird?

Wenn Sie das Feld dueDate von KursWork aktualisieren und eine benutzerdefinierte oder keine Verknüpfung mit dem Benotungszeitraum beibehalten möchten, sollten Sie dueDate und gradingPeriodId in die updateMask und den Anfragetext einfügen. Damit wird Classroom angewiesen, den gradingPeriodId nicht mit dem Benotungszeitraum zu überschreiben, 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.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId', # include the gradingPeriodId field in the updateMask
  previewVersion="V1_20240401_PREVIEW").execute()