创建和管理学生群组

您可以按照不同的用途将学生划分成不同的学生群组，以提升教学体验。例如，有的群组用于针对特定的学生布置作业，有的则用于开展协作活动。使用 Classroom API 代表管理员和教师创建、修改和读取课程中的学生群组。

您可以使用以下方法创建、更新、删除和读取学生群组：

您还可以使用以下方法在学生群组中添加、移除和读取成员：

许可和资格要求

如需在课程中创建、修改或删除学生群组，以及向学生群组添加或从中移除成员，必须满足以下条件：

读取学生群组及其成员

课程的管理员和教师可以读取学生群组数据，无论他们被分配了哪种许可。这意味着，可以代表课程中的任何管理员或教师向 ListStudentGroups 和 ListStudentGroupMembers 端点发出请求。

代码示例前提条件

本指南提供了 Python 代码示例，并假定您具备以下各项：

  • Google Cloud 项目。您可以按照 Python 快速入门中的说明进行设置。
  • 已将以下范围添加到项目的 OAuth 同意屏幕：
    • https://www.googleapis.com/auth/classroom.rosters
    • https://www.googleapis.com/auth/classroom.rosters.readonly 用于只读端点。
  • 要管理学生群组的课程的 ID。课程所有者必须拥有 Google Workspace 教育 Plus 版许可。
  • 有权访问具有 Google Workspace 教育 Plus 版许可的教师或管理员的凭据。

检查用户是否符合条件

Classroom API 提供 userProfiles.checkUserCapability 端点，可帮助您主动确定用户是否能够创建和修改学生群组及其成员。此方法可通过开发者预览版计划获取。如果您以 Python 快速入门为起点，请设置可访问预览版方法的新 Classroom 服务：

Python

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

userProfiles.checkUserCapability 端点仅评估用户是否符合使用特定功能（例如修改学生群组）的条件。它不提供有关课程角色的任何信息。例如，即使用户拥有 CREATE_STUDENT_GROUP capability，如果他们是课程中的学生，则对 CreateStudentGroup 端点的请求也不会成功。

Python

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

管理学生群组

可以使用 CreateStudentGroup 端点创建学生群组。

Python

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)

响应包含新创建的学生群组的 id、courseId 和学生群组 title。

学生组 id 可用于更新或删除个别学生组。

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

您可以使用 ListStudentGroups 端点检索课程中的学生群组：

Python

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

    studentGroups = results.get("studentGroups")

管理学生群组成员

成功创建学生群组后，您可以向其中添加成员。

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

    print(response)

如果您想从学生群组中移除某位成员，请发出如下请求：

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

您可以通过发出以下请求来读取群组中的成员：

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

    print(results.get("studentGroupMembers"))

每个 StudentGroupMember 资源都包含群组成员的 courseId、studentGroupId 和 userId。

上一页
创建和管理监护人