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 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: 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.

Lizenzanforderungen

Einstellungen für Benotungszeiträume 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:

• Dem Nutzer, der die Anfrage stellt, ist eine Google Workspace for Education Plus-Lizenz zugewiesen.
• Dem Kursinhaber ist eine Google Workspace for Education Plus-Lizenz zugewiesen.

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 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.

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 die folgenden Bereiche hinzugefügt:
  • https://www.googleapis.com/auth/classroom.courses
  • https://www.googleapis.com/auth/classroom.coursework.students
• Die ID eines Kurses, für den 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 Lizenz für Google Workspace for Education Plus 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.

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

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 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 Kursarbeit kein Abgabetermin festgelegt wurde, wird in Classroom der 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

Da die Möglichkeit, Benotungszeiträume in Classroom zu erstellen und zu ändern, nur Nutzern mit einer bestimmten Lizenz zur Verfügung steht, bietet die Classroom API den Endpunkt checkGradingPeriodsSetupEligibility. Damit können Sie proaktiv feststellen, 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. 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 der boolesche Wert 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, 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 Benotungszeiträume lesen

GradingPeriodSettings werden mit dem 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, 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

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 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 nicht in der Liste fehlen, werden als Löschungen betrachtet.
3. Benotungszeiträume mit vorhandener ID, aber geänderten Daten gelten als Änderungen. Unveränderte Properties bleiben unverändert.
4. Benotungszeiträume mit neuen oder unbekannten IDs gelten als Fehler.

Wichtig :Geben Sie in der UpdateGradingPeriodSettings-Anfrage die IDs aller Benotungszeiträume an, die Sie nicht löschen möchten.

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 wird ein neuer Benotungszeitraum hinzugefügt und der boolesche Wert applyToExistingCoursework wird 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 Kursarbeit angewendet und werden nicht aus der Kursarbeit entfernt, wenn applyToExistingCoursework in nachfolgenden Anfragen auf „False“ gesetzt wird.

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

Der boolesche Wert applyToExistingCoursework wird persistiert. Wenn er also in einem vorherigen API-Aufruf auf True gesetzt und nicht geändert wurde, werden nachfolgende Aktualisierungen der Benotungszeiträume auf vorhandene Kursarbeit 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 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 einen Benotungszeitraum löschen oder ändern, werden diese Änderungen unabhängig von der Einstellung des booleschen Werts applyToExistingCoursework auf alle vorhandenen KursArbeiten angewendet.

Wichtig: Wenn Sie das Feld applyToExistingCoursework auf False festlegen, werden vorhandene Benotungszeiträume und Verknüpfungen mit Kursarbeiten nicht entfernt. Wenn Sie den Titel eines Benotungszeitraums löschen oder ändern, wird dies unabhängig von der applyToExistingCoursework-Einstellung auf alle 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 diese Boolesche Variable auf True festlegen, werden alle konfigurierten Benotungszeiträume auf vorhandene Kursarbeit 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 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, entfernen Sie ihn aus der Liste. 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, 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 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. Verknüpfung mit datumsbasiertem Benotungszeitraum

Wenn Sie Kursarbeit erstellen, können Sie Classroom die Zuordnung der Benotungszeiträume überlassen. 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 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 verknüpfter 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 Verknüpfung mit dem Benotungszeitraum

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

Was passiert mit der Benotungszeitraum-ID, 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. 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.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()

Wichtig :Wenn Sie das Feld dueDate einer Kursaufgabe aktualisieren, fügen Sie das Feld gradingPeriodId in „updateMask“ und in den Anfragetext ein, um eine benutzerdefinierte oder keine Verknüpfung beizubehalten. So wird verhindert, dass das Feld gradingPeriodId in Classroom durch ein Feld überschrieben wird, das mit der neuen dueDate übereinstimmt.