建立及管理學生群組

學生群組可以按照用途將學生明確分組，例如指定作業和合作活動，進而提升教學體驗。您可以透過 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 for Education Plus 授權。
  • 存取老師或管理員的憑證，並具備 Google Workspace for Education 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 功能，但如果他們是課程中的學生，對 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。

上一頁
建立及管理監護人