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.
Lizenzanforderungen
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:
- 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.
ID für den Benotungszeitraum in CourseWork 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. Hiermit wird festgelegt, ob der Nutzer 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.courseshttps://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.
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 und 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 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 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, die Einstellungen für die Benotungszeiträume in einem Kurs zu ändern, 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 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 ü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, 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 an einem einzelnen Benotungszeitraum müssen dem Muster „Lesen-Ändern-Schreiben“ folgen. Beachten Sie Folgendes:
- Lesen Sie die Liste der Benotungszeiträume in der
GradingPeriodSettings-Ressource mit demGetGradingPeriodSettings-Endpunkt. - Nehmen Sie die gewünschten Änderungen an der Liste der Benotungszeiträume vor.
- Senden Sie die Liste der neuen 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:
- Benotungszeiträume, die der Liste ohne ID hinzugefügt wurden, gelten als Zusätze.
- Benotungszeiträume, die in der Liste fehlen, gelten als Löschungen.
- Benotungszeiträume mit vorhandener ID, aber geänderten Daten gelten als Änderungen. Unveränderte Properties bleiben unverändert.
- Benotungszeiträume 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“ festgelegt 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
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 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 die Benotungsfrist „Sommer“ auf alle vorhandenen Kursarbeiten angewendet, die übereinstimmen.
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 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 dieser Anleitung 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. Datumsbasierte Benotungszeitraumverknüpfung
Wenn Sie Kursarbeit erstellen, können Sie Classroom erlauben, die Zuordnung der Benotungszeiträume für Sie zu übernehmen. 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: "").
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.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()