建立及管理學生群組

學生群組可以按照用途將學生明確分組，例如指定作業和合作活動，進而提升教學體驗。代表管理員和老師，使用 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 for Education Plus 授權。
  • 存取老師或管理員的憑證，並具備 Google Workspace for Education 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。

上一頁
建立及管理監護人