Schüler-/Studentengruppen erstellen und verwalten

Mithilfe von Schüler‑/Studentengruppen können Sie Lernende zu bestimmten Gruppen zusammenfassen, um den Unterricht zu verbessern, z. B. durch gezielte Aufgaben und Gruppenaktivitäten. Mit der Classroom API können Sie im Namen von Administratoren und Lehrkräften Schüler‑/Studentengruppen in einem Kurs erstellen, ändern und lesen.

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

• CreateStudentGroup
• PatchStudentGroup
• DeleteStudentGroup
• ListStudentGroups

Mit den folgenden Methoden können Sie auch Mitglieder zu einer Schüler‑/Studentengruppe hinzufügen, daraus entfernen und lesen:

• CreateStudentGroupMember
• DeleteStudentGroupMember
• ListStudentGroupMembers

Lizenzierung und Teilnahmevoraussetzungen

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

• Der Nutzer, der die Anfrage stellt, muss eine Lehrkraft 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 Schüler‑/Studentengruppendaten 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

Dieser Leitfaden enthält Codebeispiele in Python. Dabei wird davon ausgegangen, dass Sie Folgendes haben:

• Ein Google Cloud-Projekt. Sie können eines gemäß der Anleitung in der Python-Kurzanleitung einrichten.
• Die folgenden Bereiche wurden dem OAuth-Zustimmungsbildschirm Ihres Projekts hinzugefügt:
  • https://www.googleapis.com/auth/classroom.rosters
  • https://www.googleapis.com/auth/classroom.rosters.readonly für schreibgeschützte Endpunkte.
• Eine ID eines Kurses, in dem Schüler‑/Studentengruppen verwaltet werden sollen. Der Kurs inhaber 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.

Berechtigung des Nutzers prüfen

Die Classroom API bietet den userProfiles.checkUserCapability Endpunkt, mit dem Sie proaktiv feststellen können, ob ein Nutzer Schüler‑/Studentengruppen und deren Mitglieder erstellen und ändern kann. Die Methode ist über das Entwicklervorschauprogramm verfügbar. Wenn Sie die Python-Kurzanleitung als Ausgangspunkt verwendet haben, richten Sie einen neuen Classroom-Dienst ein, der auf Vorschau-Methoden 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')

Der Endpunkt userProfiles.checkUserCapability prüft nur, ob ein Nutzer berechtigt ist, eine bestimmte Funktion zu verwenden, z. B. Schüler‑/Studentengruppen zu ändern. Er enthält keine Informationen zur Kursrolle. Auch wenn ein Nutzer die Funktion CREATE_STUDENT_GROUP hat, kann eine Anfrage an den Endpunkt CreateStudentGroup nicht erfolgreich sein, wenn er ein Schüler/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 mit dem 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 den title der Schüler‑/Studentengruppe.

Die id der Schüler‑/Studentengruppe kann verwendet werden, um die einzelne Schüler‑/Studentengruppe zu aktualisieren oder zu 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)

Mit dem Endpunkt ListStudentGroups können Sie die Schüler‑/Studentengruppen in einem Kurs 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üler‑/Studentengruppe erfolgreich erstellt wurde, können Sie 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)

Mit der folgenden Anfrage können Sie die Mitglieder einer Gruppe 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.