Schüler-/Studentengruppen erstellen und verwalten

Mithilfe von Schüler‑/Studentengruppen können Sie Lernende zu verschiedenen Zwecken in bestimmte Gruppen einteilen, z. B. für gezielte Aufgaben und Gruppenaktivitäten. Mit der Classroom API können Sie im Namen von Administratoren und Lehrkräften Schülergruppen in einem Kurs erstellen, ändern und lesen.

Sie können Schüler-/Studentengruppen mit den folgenden Methoden erstellen, aktualisieren, löschen und lesen:

Sie können auch Mitglieder in einer Schülergruppe hinzufügen, entfernen und lesen. Verwenden Sie dazu die folgenden Methoden:

Auf Methoden für Schülergruppen im Programm der Entwicklervorschau zugreifen

So greifen Sie auf die Methoden für Schülergruppen in der Vorschau zu:

Lizenzierungs- und Teilnahmevoraussetzungen

Damit Sie Schüler-/Studentengruppen in einem Kurs erstellen, ändern oder löschen und Mitglieder hinzufügen oder entfernen können, müssen die folgenden Bedingungen erfüllt sein:

Schüler-/Studentengruppen und ihre Mitglieder lesen

Administratoren und Lehrkräfte eines Kurses können Daten zu Schüler-/Studentengruppen lesen, unabhängig davon, welche Lizenz ihnen zugewiesen ist. Das bedeutet, dass Anfragen an die Endpunkte ListStudentGroups und ListStudentGroupMembers im Namen eines beliebigen Administrators oder einer beliebigen Lehrkraft in einem Kurs zulässig sind.

Voraussetzungen für Codebeispiele

In diesem Leitfaden finden Sie Codebeispiele in Python. Außerdem wird davon ausgegangen, dass Sie Folgendes haben:

  • 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.rosters
    • https://www.googleapis.com/auth/classroom.rosters.readonly für schreibgeschützte Endpunkte.
  • Die ID eines Kurses, in dem Schüler‑/Studentengruppen verwaltet 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.

Wenn Sie die Python-Kurzanleitung als Ausgangspunkt verwendet haben, ändern Sie den Classroom-Dienst, um auf Preview-Methoden zuzugreifen.

Python

classroom_service = googleapiclient.discovery.build(
    serviceName='classroom',
    version='v1',
    credentials=creds,
    static_discovery=False,
    discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY')

Nutzerberechtigung prüfen

Die Classroom API bietet den userProfiles.checkUserCapability-Endpunkt, mit dem Sie proaktiv ermitteln können, ob ein Nutzer Schülergruppen und deren Mitglieder erstellen und ändern kann.

Der userProfiles.checkUserCapability-Endpunkt prüft nur, ob ein Nutzer berechtigt ist, eine bestimmte Funktion zu verwenden, z. B. Schülergruppen zu ändern. Sie enthält keine Informationen zur Kursrolle. Auch wenn ein Nutzer beispielsweise die Funktion CREATE_STUDENT_GROUP hat, wird eine Anfrage an den Endpunkt CreateStudentGroup nicht erfolgreich sein, wenn er ein Schüler oder Student im Kurs ist.

Python

def check_student_groups_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify student groups in a course."""
    capability = classroom_service.userProfiles().checkUserCapability(
        userId="me", # Can also be set to a different user's email address or ID
        capability="CREATE_STUDENT_GROUP",
        previewVersion="V1_20240930_PREVIEW" # Required while the method is in the DPP.
    ).execute()

    if capability.get("allowed"): # Retrieve the `allowed` boolean from the response.
        print("User is allowed to create and modify student groups.")
    else:
        print("User is not allowed to create and modify student groups.")

Schüler‑/Studentengruppen verwalten

Schüler-/Studentengruppen können mit dem CreateStudentGroup-Endpunkt erstellt werden.

Python

def create_student_group(classroom_service, course_id):
    body = {
        "title": "Team Blue"
    }

    response = classroom_service.courses().studentGroups().create(
        courseId=course_id,
        body=body,
        previewVersion="V1_20250630_PREVIEW",
    ).execute()

    print(response)

Die Antwort enthält die id der neu erstellten Schüler-/Studentengruppe, die courseId und die Schüler-/Studentengruppe title.

Mit der Schüler-/Studentengruppe id können Sie die einzelne Schüler-/Studentengruppe aktualisieren oder löschen.

Python

def update_student_group(classroom_service, course_id, student_group_id):
    body = {
        "title": "Team Green"
    }

    response = classroom_service.courses().studentGroups().patch(
        courseId=course_id,
        id=student_group_id,
        body=body,
        updateMask="title",
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(response)

def delete_student_group(classroom_service, course_id, student_group_id):
    response = classroom_service.courses().studentGroups().delete(
        courseId=course_id,
        id=student_group_id,
        previewVersion="V1_20250630_PREVIEW",
    ).execute()

    print(response)

Sie können die Schüler-/Studentengruppen in einem Kurs mit dem Endpunkt ListStudentGroups abrufen:

Python

def list_student_groups(classroom_service, course_id):
    results = classroom_service.courses().studentGroups().list(
        courseId=course_id,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    studentGroups = results.get("studentGroups")

Mitglieder von Schüler‑/Studentengruppen verwalten

Nachdem die Schülergruppe erfolgreich erstellt wurde, können Sie ihr Mitglieder hinzufügen.

Python

def add_student_group_member(classroom_service, course_id, student_group_id):
    body = {
        "userId": "student@schooldomain.com"
    }

    response = classroom_service.courses().studentGroups().studentGroupMembers().create(
        courseId=course_id,
        studentGroupId=student_group_id,
        body=body,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(response)

Wenn Sie ein Mitglied aus einer Schüler-/Studentengruppe entfernen möchten, stellen Sie eine Anfrage wie die folgende:

Python

def delete_student_group_member(classroom_service, course_id, student_group_id):
    response = classroom_service.courses().studentGroups().studentGroupMembers().delete(
        courseId=course_id,
        studentGroupId=student_group_id,
        userId="student@schooldomain.com",
        previewVersion="V1_20250630_PREVIEW"
    ).execute()
    print(response)

Sie können die Mitglieder einer Gruppe mit der folgenden Anfrage lesen:

Python

def list_student_group_members(classroom_service, course_id, student_group_id):
    results = classroom_service.courses().studentGroups().studentGroupMembers().list(
        courseId=course_id,
        studentGroupId=student_group_id,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(results.get("studentGroupMembers"))

Jede StudentGroupMember-Ressource enthält die courseId, studentGroupId und userId des Gruppenmitglieds.

Zurück
Erziehungsberechtigte erstellen und verwalten