Создавайте и управляйте студенческими группами

Вы можете использовать группы учащихся для организации их в определённые группы для повышения эффективности обучения, например, для адресных заданий и совместной работы. Используйте API Classroom для создания, изменения и чтения групп учащихся в рамках курса от имени администраторов и преподавателей.

Вы можете создавать, обновлять, удалять и читать группы студентов, используя следующие методы:

• CreateStudentGroup
• PatchStudentGroup
• DeleteStudentGroup
• ListStudentGroups

Вы также можете добавлять, удалять и читать список участников студенческой группы, используя следующие методы:

• CreateStudentGroupMember
• DeleteStudentGroupMember
• ListStudentGroupMembers

Доступ к методам студенческих групп в программе Developer Preview

Чтобы получить доступ к методам групп студентов в предварительном просмотре, необходимо сделать следующее:

• Присоединяйтесь к программе предварительного просмотра для разработчиков (DPP).
• Настройте клиентскую библиотеку для доступа к функциям предварительной версии. Методы в DPP не представлены в стандартных клиентских библиотеках и стандартных HTTP-запросах. После успешного присоединения к DPP вы сможете получить доступ к клиентским библиотекам студенческих групп для определённых языков программирования и загрузить их. Чтобы узнать, как настроить предварительную версию и метку для выбранной клиентской библиотеки, посетите страницу API предварительной версии Access .
• Задайте версию предварительного просмотра и метку предварительного просмотра при выполнении запросов к API. Для методов групп студентов версия предварительного просмотра — V1_20250630_PREVIEW , а метка предварительного просмотра — DEVELOPER_PREVIEW . Примеры запросов к API с предварительной версией можно найти в разделе «Управление группами студентов» .

Требования к лицензированию и квалификации

Для создания, изменения или удаления групп студентов на курсе, а также добавления или удаления участников из групп студентов должны быть выполнены следующие условия:

• Пользователь, отправляющий запрос, должен быть преподавателем курса или администратором домена.
• Пользователь, подающий запрос, должен иметь назначенную ему лицензию Google Workspace for Education Plus .
• Владельцу курса должна быть назначена лицензия Google Workspace for Education Plus .

Чтение студенческих групп и их участников

Администраторы и преподаватели курса могут читать данные групп студентов независимо от назначенной им лицензии. Это означает, что запросы к конечным точкам ListStudentGroups и ListStudentGroupMembers разрешены от имени любого администратора или преподавателя курса.

Предварительные условия для примера кода

В этом руководстве приведены примеры кода на Python. Предполагается, что у вас есть следующее:

• Проект Google Cloud. Вы можете настроить его, следуя инструкциям в кратком руководстве по Python .
• Добавлены следующие области действия на экран согласия OAuth вашего проекта:
  • https://www.googleapis.com/auth/classroom.rosters
  • https://www.googleapis.com/auth/classroom.rosters.readonly для конечных точек только для чтения.
• Идентификатор курса, в рамках которого необходимо управлять группами студентов. Владелец курса должен иметь лицензию Google Workspace for Education Plus .
• Доступ к учетным данным преподавателя или администратора с лицензией Google Workspace for Education Plus .

Если вы использовали краткое руководство по Python в качестве отправной точки, измените службу Classroom для доступа к методам предварительного просмотра.

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

Проверить право пользователя

API класса предоставляет конечную точку userProfiles.checkUserCapability , которая поможет вам заблаговременно определить, может ли пользователь создавать и изменять группы учащихся и их участников.

Конечная точка userProfiles.checkUserCapability оценивает только право пользователя использовать определённую возможность, например, изменять группы студентов. Она не предоставляет никакой информации о роли на курсе. Например, даже если у пользователя есть возможность CREATE_STUDENT_GROUP , но он является студентом курса, запрос к конечной точке CreateStudentGroup не будет выполнен.

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

Управление студенческими группами

Группы студентов можно создавать с помощью конечной точки 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)

Ответ содержит id вновь созданной студенческой группы, courseId и title студенческой группы.

id студенческой группы можно использовать для обновления или удаления отдельной студенческой группы.

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)

Вы можете получить группы студентов в пределах курса, используя конечную точку 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")

Управление членами студенческой группы

После успешного создания студенческой группы вы можете добавлять в нее участников.

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)

Если вы хотите удалить участника из студенческой группы, подайте запрос следующего вида:

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)

Вы можете просмотреть список участников группы, сделав следующий запрос:

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

Каждый ресурс StudentGroupMember включает courseId , studentGroupId и userId члена группы.