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:

• CreateStudentGroup
• PatchStudentGroup
• DeleteStudentGroup
• ListStudentGroups

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

• CreateStudentGroupMember
• DeleteStudentGroupMember
• ListStudentGroupMembers

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:

• Der Nutzer, der die Anfrage stellt, muss ein Kursleiter im Kurs oder ein Administrator der Domain sein.
• Dem Nutzer, der die Anfrage stellt, muss eine Google Workspace for Education Plus-Lizenz zugewiesen sein.
• Dem Kursinhaber muss eine Google Workspace for Education Plus-Lizenz zugewiesen 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.

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. Die Methode ist über das Programm der Entwicklervorschau verfügbar. Wenn Sie die Python-Kurzanleitung als Ausgangspunkt verwendet haben, richten Sie einen neuen Classroom-Dienst ein, der auf Vorabmethoden zugreifen kann:

classroom_service_with_capability_endpoint = 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')

Mit dem userProfiles.checkUserCapability-Endpunkt wird nur geprüft, 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.

def check_student_groups_update_capability():
    """Checks whether a user is eligible to create and modify student groups."""
    capability = classroom_service_with_capability_endpoint.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 eligible to create and modify student groups.")
    else:
        print("User is not eligible to create and modify student groups.")

Schüler‑/Studentengruppen verwalten

Schüler-/Studentengruppen können über den CreateStudentGroup-Endpunkt erstellt werden.

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

    response = classroom_service.courses().studentGroups().create(
        courseId=course_id,
        body=body
    ).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.

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"
    ).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
    ).execute()

    print(response)

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

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

    studentGroups = results.get("studentGroups")

Mitglieder von Schüler‑/Studentengruppen verwalten

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

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
    ).execute()

    print(response)

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

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"
    ).execute()
    print(response)

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

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
    ).execute()

    print(results.get("studentGroupMembers"))

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