创建和管理学生群组

您可以将学生划分成不同的学生群组，以便开展有针对性的作业和协作活动，从而提升教学体验。使用 Classroom API 代表管理员和教师创建、修改和读取课程中的学生群组。

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

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

在开发者预览版计划中访问学生群组方法

如需访问预览版中的学生群组方法，您必须执行以下操作：

  • 加入开发者预览版计划 (DPP)。
  • 设置客户端库以访问预览版功能。DPP 中的方法不会在标准客户端库和标准 HTTP 请求中公开。成功加入 DPP 后，您可以访问并下载特定编程语言的学生群组客户端库。如需了解如何使用预览版和标签设置所选的客户端库，请参阅访问预览版 API 页面。
  • 在发出 API 请求时设置预览版和预览标签。对于学生群组方法，预览版为 V1_20250630_PREVIEW，预览标签为 DEVELOPER_PREVIEW。您可以在管理学生群组部分中找到使用预览版的 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 版许可的教师或管理员的凭据。

如果您以 Python 快速入门为起点，请修改 Classroom 服务以访问预览版方法。

Python

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

检查用户资格

Classroom API 提供 userProfiles.checkUserCapability 端点，可帮助您主动确定用户是否能够创建和修改学生群组及其成员。

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

Python

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 端点创建学生群组。

Python

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 可用于更新或删除个别学生组。

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",
        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 端点检索课程中的学生群组：

Python

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

管理学生群组成员

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

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,
        previewVersion="V1_20250630_PREVIEW"
    ).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",
        previewVersion="V1_20250630_PREVIEW"
    ).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,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(results.get("studentGroupMembers"))

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

上一页
创建和管理监护人