Bạn có thể sử dụng nhóm học viên để sắp xếp học viên thành các nhóm riêng biệt nhằm nâng cao trải nghiệm giảng dạy, chẳng hạn như giao bài tập theo mục tiêu cụ thể và các hoạt động cộng tác. Sử dụng Classroom API để tạo, sửa đổi và đọc các nhóm học viên trong một khoá học thay mặt cho quản trị viên và giáo viên.
Bạn có thể tạo, cập nhật, xoá và đọc nhóm học viên bằng các phương thức sau:
Bạn cũng có thể thêm, xoá và đọc các thành viên trong một nhóm học viên bằng các phương thức sau:
Truy cập vào các phương thức nhóm học viên trong Chương trình dùng thử cho nhà phát triển
Các điểm cuối của nhóm học viên đang ở giai đoạn dùng thử, tức là bạn phải tham gia Chương trình dùng thử dành cho nhà phát triển (DPP) để gửi yêu cầu đến các điểm cuối này. Để biết thông tin về cách tham gia DPP, hãy truy cập vào trang xem trước các tính năng và lộ trình.
Các điểm cuối trong DPP không được hiển thị trong các thư viện ứng dụng tiêu chuẩn và yêu cầu HTTP tiêu chuẩn. Sau khi tham gia DPP, bạn phải thêm nhãn xem trước và phiên bản xem trước khi đưa ra yêu cầu API. Đối với các điểm cuối nhóm học viên, nhãn xem trước là DEVELOPER_PREVIEW và phiên bản xem trước là V1_20250630_PREVIEW. Để biết thông tin về cách đưa nhãn xem trước và phiên bản xem trước vào mã ứng dụng, hãy xem trang Truy cập vào các API xem trước.
Yêu cầu về giấy phép và điều kiện
Để tạo, sửa đổi hoặc xoá nhóm học viên trong một khoá học và thêm hoặc xoá thành viên khỏi nhóm học viên, bạn phải đáp ứng các điều kiện sau:
- Người dùng đưa ra yêu cầu phải là giáo viên trong khoá học hoặc quản trị viên của miền.
- Người dùng đưa ra yêu cầu phải được cấp giấy phép Google Workspace for Education Plus.
- Chủ sở hữu khoá học phải được cấp giấy phép Google Workspace for Education Plus.
Đọc thông tin về nhóm học viên và thành viên của nhóm
Quản trị viên và giáo viên của một khoá học có thể đọc dữ liệu nhóm học viên bất kể họ được chỉ định loại giấy phép nào. Điều này có nghĩa là các yêu cầu đến các điểm cuối ListStudentGroups và ListStudentGroupMembers được cho phép thay mặt cho bất kỳ quản trị viên hoặc giáo viên nào trong một khoá học.
Điều kiện tiên quyết
Hướng dẫn này cung cấp các ví dụ về mã bằng Python và giả định rằng bạn đáp ứng các điều kiện sau:
- Một dự án trên Google Cloud. Bạn có thể thiết lập một ứng dụng theo hướng dẫn trong bài viết Hướng dẫn nhanh về Python.
- Thêm các phạm vi sau vào màn hình xin phép bằng OAuth của dự án:
https://www.googleapis.com/auth/classroom.rostershttps://www.googleapis.com/auth/classroom.rosters.readonlycho các điểm cuối chỉ có thể đọc.
- Mã nhận dạng của một khoá học mà bạn cần quản lý các nhóm học viên. Chủ sở hữu khoá học phải có giấy phép Google Workspace for Education Plus.
- Có thông tin đăng nhập của giáo viên hoặc quản trị viên có giấy phép Google Workspace for Education Plus.
Kiểm tra điều kiện sử dụng của người dùng
Classroom API cung cấp điểm cuối userProfiles.checkUserCapability để giúp bạn chủ động xác định xem người dùng có thể tạo và sửa đổi nhóm học viên cũng như thành viên của nhóm đó hay không.
Điểm cuối userProfiles.checkUserCapability chỉ đánh giá xem người dùng có đủ điều kiện sử dụng một chức năng nhất định hay không, chẳng hạn như sửa đổi nhóm học viên. Trang này không cung cấp thông tin nào về vai trò của khoá học. Ví dụ: ngay cả khi người dùng có khả năng CREATE_STUDENT_GROUP, nếu họ là học viên trong khoá học, thì yêu cầu đến điểm cuối CreateStudentGroup sẽ không thành công.
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.")
Quản lý nhóm học viên
Bạn có thể tạo nhóm học viên bằng điểm cuối 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)
Phản hồi chứa id của nhóm học viên mới tạo, courseId và title của nhóm học viên.
Bạn có thể dùng nhóm học viên id để cập nhật hoặc xoá nhóm học viên riêng lẻ.
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)
Bạn có thể truy xuất các nhóm học viên trong một khoá học bằng cách sử dụng điểm cuối 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")
Quản lý thành viên trong nhóm học viên
Sau khi tạo nhóm học viên thành công, bạn có thể thêm thành viên vào nhóm đó.
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)
Nếu bạn muốn xoá một thành viên khỏi nhóm học viên, hãy đưa ra yêu cầu như sau:
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)
Bạn có thể đọc các thành viên trong một nhóm bằng cách đưa ra yêu cầu sau:
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"))
Mỗi tài nguyên StudentGroupMember đều bao gồm courseId, studentGroupId và userId của thành viên nhóm.