Benotungszeiträume mit der Classroom API verwalten

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

Übersicht

Benotungszeiträume werden erstellt, um Hausaufgaben, Quizze und Projekte in bestimmte Zeiträume 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 Kursarbeit festzulegen.

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

  • GetGradingPeriodSettings: Hier können Sie die Einstellungen für die Benotungszeiträume in einem Kurs aufrufen.
  • UpdateGradingPeriodSettings: Hier 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 Kursmaterialien anwenden.

Lizenzierung und Teilnahmevoraussetzungen

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

Damit Sie Benotungszeiträume in einem Kurs über den Endpunkt UpdateGradingPeriodSettings erstellen, ändern oder löschen können, müssen die folgenden Bedingungen erfüllt sein:

Einstellungen für Benotungszeiträume in einem Kurs lesen

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

Benotungszeitraum-ID für Kursarbeit festlegen

Lehrkräfte eines Kurses können die gradingPeriodId beim Erstellen oder Aktualisieren von Kursmaterialien mit der API angeben, unabhängig von der zugewiesenen Lizenz.

Prüfen, ob ein Nutzer Benotungszeiträume einrichten kann

Anfragen an den Endpunkt userProfiles.checkUserCapability sind im Namen eines Administrators oder einer Lehrkraft zulässig. Hiermit wird festgelegt, ob der Nutzer Benotungszeiträ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.
  • 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
  • Die ID eines Kurses, in dem die Benotungszeiträume geändert werden sollen. Der Kursinhaber benötigt eine Google Workspace for Education Plus-Lizenz.
  • Zugriff auf die Anmeldedaten einer Lehrkraft oder eines Administrators mit einer Google Workspace for Education Plus-Lizenz Sie benötigen die Anmeldedaten eines Lehrkräfte, um Kursarbeit zu erstellen oder zu ändern. Administratoren können keine Kursarbeit erstellen oder ändern, wenn sie keine Lehrkraft im Kurs sind.

GradingPeriodSettings-Ressource verwalten

Die GradingPeriodSettings-Ressource enthält eine Liste einzelner GradingPeriods und ein boolesches Feld namens applyToExistingCoursework.

Achten Sie darauf, dass jede einzelne GradingPeriods in der Liste die folgenden Anforderungen erfüllt:

  • 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 nicht mit dem Titel anderer Benotungszeiträume im Kurs übereinstimmt.
  • Keine Überschneidungen: Die Start- und Enddaten der einzelnen Benotungszeiträume dürfen sich nicht mit denen anderer Benotungszeiträume im Kurs überschneiden.
  • Chronologisch: Benotungszeiträume müssen anhand der Start- und Enddaten in chronologischer Reihenfolge aufgelistet werden.

Jedem Benotungszeitraum wird bei der Erstellung eine von der Classroom API zugewiesene Kennung zugewiesen.

Der boolesche Wert applyToExistingCoursework ist eine persistente Einstellung, mit der Sie zuvor erstellte Kursleistungen in Benotungszeiträume unterteilen können, ohne einen separaten API-Aufruf ausführen zu müssen, um die gradingPeriodId für jede Kursleistung zu ändern. Wenn es auf True festgelegt ist, wird in Classroom automatisch der gradingPeriodId für alle vorhandenen Kursmaterialien festgelegt, wenn der courseWork.dueDate in den Start- und Endzeitraum eines vorhandenen Benotungszeitraums fällt. Wenn für die Kursarbeit kein Abgabetermin festgelegt wurde, wird in Classroom courseWork.scheduledTime verwendet. Wenn keines der beiden Felder vorhanden ist oder keine Übereinstimmung mit den Start- und Enddaten eines vorhandenen Benotungszeitraums besteht, wird die Kursarbeit keinem Benotungszeitraum zugeordnet.

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

Die Classroom API bietet den Endpunkt userProfiles.checkUserCapability, mit dem Sie proaktiv feststellen 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

Da Sie nun sicher sind, dass der Nutzer die Einstellungen für die Benotungszeiträume in einem Kurs ändern darf, können Sie Anfragen an den UpdateGradingPeriodSettings-Endpunkt senden. Alle Änderungen an der Ressource GradingPeriodSettings werden über den Endpunkt UpdateGradingPeriodSettings ausgeführt, 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 gradingPeriodSettings-Ressource so geändert, dass sie zwei Benotungszeiträume enthält. Wenn das boolesche applyToExistingCoursework auf True festgelegt ist, wird die gradingPeriodId für alle vorhandenen Kursarbeiten geändert, die zwischen dem Start- und Enddatum eines Benotungszeitraums 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 Endpunkt GetGradingPeriodSettings gelesen. Alle Nutzer, unabhängig von ihrer Lizenz, können die Einstellungen für 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

Liste einen einzelnen Benotungszeitraum hinzufügen

Änderungen an einem einzelnen Benotungszeitraum müssen dem Muster „Lesen-Ändern-Schreiben“ folgen. 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 Liste der neuen Benotungszeiträume in einer Anfrage an UpdateGradingPeriodSettings.

So können Sie dafür sorgen, dass die Titel der einzelnen Benotungszeiträume in einem Kurs eindeutig sind und sich die Start- und Enddaten der Benotungszeiträume nicht überschneiden.

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

  1. Benotungszeiträume, die der Liste ohne ID hinzugefügt wurden, gelten als Zusätze.
  2. Benotungszeiträume, die in der Liste fehlen, gelten als Löschungen.
  3. Benotungszeiträume mit vorhandener ID, aber geänderten Daten gelten als Änderungen. Unveränderte Properties bleiben unverändert.
  4. Benotungszeitraume mit neuen oder unbekannten IDs gelten als Fehler.

Python

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

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

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 persistiert. Wenn er also in einem vorherigen API-Aufruf auf True festgelegt und nicht geändert wurde, werden nachfolgende Aktualisierungen der Benotungszeiträume auf vorhandene Kursarbeit angewendet.

Wenn Sie diesen booleschen Wert in einer Anfrage an UpdateGradingPeriodSettings von True in False ändern, werden nur die neuen Änderungen an GradingPeriodSettings nicht auf vorhandene Kursarbeit angewendet. Informationen zum Benotungszeitraum, die in vorherigen API-Aufrufen auf Kursarbeit angewendet wurden, wenn der boolesche Wert auf True gesetzt war, werden nicht entfernt. Mit dieser booleschen Einstellung können Sie vorhandene Kursleistungen mit Ihren konfigurierten Benotungszeiträumen verknüpfen. Es ist jedoch nicht möglich, vorhandene Verknüpfungen zwischen Kursleistungen und konfigurierten Benotungszeiträumen zu entfernen.

Wenn Sie den Titel eines Benotungszeitraums löschen oder ändern, werden diese Änderungen unabhängig von der Einstellung des booleschen Werts applyToExistingCoursework auf alle vorhandenen Kursmaterialien angewendet.

Einen einzelnen Benotungszeitraum in der Liste aktualisieren

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

Python

In diesem Beispiel wird das Enddatum des Benotungszeitraums „Sommer“ geändert. Das Feld applyToExistingCoursework wird auf True gesetzt. Hinweis: Wenn Sie diesen booleschen Wert auf True festlegen, werden alle konfigurierten Benotungszeiträume auf vorhandene Kursarbeiten angewendet. In der vorherigen API-Anfrage wurde der boolesche Wert auf False festgelegt, damit die Benotungsfrist „Sommer“ nicht auf vorhandene Kursarbeiten angewendet wurde. Da dieses boolesche Feld jetzt auf True gesetzt ist, wird die Benotungsfrist „Sommer“ auf alle vorhandenen Kursarbeiten 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 einfach aus der Liste aus. Hinweis: Wenn ein Benotungszeitraum gelöscht wird, werden unabhängig von der applyToExistingCoursework-Einstellung auch alle Verweise auf den Benotungszeitraum in CourseWork gelöscht.

Python

Um mit dem Beispiel in diesem Leitfaden fortzufahren, lassen Sie den Benotungszeitraum „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 Kursressource enthält das Feld gradingPeriodId. Mit Kursaufgaben-Endpunkten können Sie den mit einer Kursarbeit verknüpften Benotungszeitraum lesen und schreiben. Es gibt drei Möglichkeiten, diese Verknüpfung zu verwalten:

  • Automatische befristete Benotungszeitraumverknüpfung
  • Benutzerdefinierter zugeordneter Benotungszeitraum
  • keine Benotungszeitraumverknüpfung

1. Datumsbasierte Benotungszeitraumverknüpfung

Wenn Sie Kursarbeit erstellen, können Sie Classroom die Zuordnung der Benotungszeiträume überlassen. Lassen Sie dazu das Feld gradingPeriodId aus der Kursarbeitsanfrage aus. Geben Sie dann die Felder dueDate oder scheduledTime in der Kursarbeitsanfrage an. Wenn das dueDate in den Zeitraum eines vorhandenen Benotungszeitraums fällt, wird in Classroom die ID dieses Benotungszeitraums für die Kursarbeit festgelegt. Wenn das Feld dueDate nicht angegeben ist, wird gradingPeriodId in Classroom anhand des Felds scheduledTime ermittelt. Wenn keines der beiden Felder angegeben ist oder kein Übereinstimmung zwischen dem Benotungszeitraum und dem Zeitraum besteht, wird für die Kursarbeit kein gradingPeriodId festgelegt.

2. Benutzerdefinierter zugeordneter Benotungszeitraum

Wenn Sie die Kursarbeit 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 der Kursarbeit manuell festlegen. Wenn Sie die gradingPeriodId manuell festlegen, wird in Classroom keine automatische befristete Zuordnung von Benotungszeiträumen vorgenommen.

3. Keine Benotungszeitraumverknüpfung

Wenn die Kursarbeit mit keinem Benotungszeitraum verknüpft werden soll, setzen Sie das Feld gradingPeriodId in der Kursarbeitsanfrage auf einen leeren String (gradingPeriodId: "").

Wenn Sie die Programmiersprache Go verwenden und keinen Benotungszeitraum festlegen möchten, sollten Sie auch das Feld ForceSendFields in den Anfragetext aufnehmen. Bei der Go-Clientbibliothek werden Standardwerte aus API-Anfragen entfernt, da sich das Feld-Tag omitempty auf allen Feldern befindet. Das Feld ForceSendFields umgeht dies und sendet den leeren String, um anzugeben, dass für diese Kursarbeit kein Benotungszeitraum festgelegt werden soll. Weitere Informationen finden Sie in der Dokumentation zur Google APIs Go-Clientbibliothek.

Ok

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

Was passiert mit der Benotungszeitraum-ID, wenn der Abgabetermin aktualisiert wird?

Wenn Sie das Feld „CourseWork“ dueDate aktualisieren und eine benutzerdefinierte oder keine Zuordnung zu einem Benotungszeitraum beibehalten möchten, sollten Sie dueDate und gradingPeriodId in die updateMask und den Anfragetext aufnehmen. Dadurch wird Classroom angewiesen, die gradingPeriodId nicht mit dem Benotungszeitraum zu überschreiben, der der 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()