Tworzenie grup uczniów i zarządzanie nimi

Grupy uczniów możesz tworzyć w różnych celach, np. związanych z przypisywaniem ukierunkowanych projektów czy współpracą. Używaj interfejsu Classroom API do tworzenia, modyfikowania i odczytywania grup uczniów w ramach kursu w imieniu administratorów i nauczycieli.

Grupy uczniów możesz tworzyć, aktualizować, usuwać i odczytywać za pomocą tych metod:

• CreateStudentGroup
• PatchStudentGroup
• DeleteStudentGroup
• ListStudentGroups

Możesz też dodawać i usuwać członków grupy uczniów oraz czytać ich posty, korzystając z tych metod:

• CreateStudentGroupMember
• DeleteStudentGroupMember
• ListStudentGroupMembers

Dostęp do metod grup uczniów w ramach programu podglądu dla deweloperów

Aby uzyskać dostęp do metod grup uczniów w wersji podglądowej, musisz wykonać te czynności:

• Dołącz do Programu testowania wersji deweloperskich (DPP).
• Skonfiguruj bibliotekę klienta, aby uzyskać dostęp do funkcji w wersji przedpremierowej. Metody w DPP nie są udostępniane w standardowych bibliotekach klienta ani standardowych żądaniach HTTP. Po dołączeniu do programu DPP możesz uzyskać dostęp do bibliotek klienta grup uczniów dla określonych języków programowania i je pobrać. Aby dowiedzieć się, jak skonfigurować wybraną bibliotekę klienta z wersją i etykietą wersji zapoznawczej, zapoznaj się ze stroną Uzyskiwanie dostępu do interfejsów API w wersji zapoznawczej.
• Podczas wysyłania żądań do interfejsu API ustaw wersję podglądu i etykietę podglądu. W przypadku metod grup uczniów wersja podglądowa to V1_20250630_PREVIEW, a etykieta podglądu to DEVELOPER_PREVIEW. Przykłady żądań interfejsu API w wersji podglądowej znajdziesz w sekcji Zarządzanie grupami uczniów.

Wymagania dotyczące licencji i kryteria kwalifikacji

Aby utworzyć, zmodyfikować lub usunąć grupy uczniów na kursie oraz dodać lub usunąć członków z grup uczniów, musisz spełnić te warunki:

• Użytkownik wysyłający prośbę musi być nauczycielem na zajęciach lub administratorem domeny.
• Użytkownik wysyłający prośbę musi mieć przypisaną licencję na Google Workspace for Education Plus.
• Właściciel kursu musi mieć przypisaną licencję Google Workspace for Education Plus.

Odczytywanie grup uczniów i ich członków

Administratorzy i nauczyciele zajęć mogą odczytywać dane grup uczniów niezależnie od przypisanej licencji. Oznacza to, że żądania wysyłane do punktów końcowych ListStudentGroups i ListStudentGroupMembers są dozwolone w imieniu dowolnego administratora lub nauczyciela na kursie.

Wymagania wstępne dotyczące przykładowego kodu

W tym przewodniku znajdziesz przykłady kodu w Pythonie. Zakładamy, że masz:

• Projekt Google Cloud. Możesz go skonfigurować, postępując zgodnie z instrukcjami w tym przewodniku.
• Dodano te zakresy do ekranu zgody OAuth w projekcie:
  • https://www.googleapis.com/auth/classroom.rosters
  • https://www.googleapis.com/auth/classroom.rosters.readonly w przypadku punktów końcowych tylko do odczytu.
• Identyfikator kursu, w którym należy zarządzać grupami uczniów. Właściciel kursu musi mieć licencję Google Workspace for Education Plus.
• Dostęp do danych logowania nauczyciela lub administratora z licencją Google Workspace for Education Plus.

Jeśli jako punkt wyjścia posłużył Ci krótki przewodnik po Pythonie, zmodyfikuj usługę Classroom, aby uzyskać dostęp do metod w wersji przedpremierowej.

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

Sprawdzanie, czy użytkownik spełnia wymagania

Interfejs Classroom API udostępnia punkt końcowy userProfiles.checkUserCapability, który pomaga proaktywnie określać, czy użytkownik może tworzyć i modyfikować grupy uczniów oraz ich członków.

Punkt końcowy userProfiles.checkUserCapability sprawdza tylko, czy użytkownik może korzystać z określonej funkcji, np. modyfikować grupy uczniów. Nie zawiera żadnych informacji o roli w kursie. Na przykład nawet jeśli użytkownik ma uprawnienia CREATE_STUDENT_GROUP, ale jest uczniem na kursie, żądanie wysłane do punktu końcowego CreateStudentGroup nie zostanie zrealizowane.

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

Zarządzanie grupami uczniów

Grupy uczniów można tworzyć za pomocą punktu końcowego CreateStudentGroup.

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)

Odpowiedź zawiera id nowo utworzonej grupy uczniów, courseId i title grupy uczniów.

Grupa uczniówid może służyć do aktualizowania lub usuwania grupy poszczególnych uczniów.

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)

Grupy uczniów w ramach kursu możesz pobrać za pomocą punktu końcowego ListStudentGroups:

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")

Zarządzanie członkami grupy uczniów

Po utworzeniu grupy uczniów możesz dodać do niej członków.

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)

Jeśli chcesz usunąć członka z grupy uczniów, wyślij prośbę podobną do tej:

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)

Aby odczytać członków grupy, wyślij to żądanie:

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"))

Każdy zasób StudentGroupMember zawiera courseId, studentGroupId i userId członka grupy.