학생 그룹을 사용하면 학생들을 타겟팅된 과제 및 공동작업 활동과 같은 향상된 교육 환경을 위한 그룹으로 나눌 수 있습니다. Classroom API를 사용하여 관리자 및 교사를 대신하여 수업 내 학생 그룹을 만들고, 수정하고, 읽습니다.
다음 방법을 사용하여 학생 그룹을 생성, 업데이트, 삭제, 읽을 수 있습니다.
다음 방법을 사용하여 학생 그룹 내에서 구성원을 추가, 삭제, 읽을 수도 있습니다.
개발자 프리뷰 프로그램에서 학생 그룹 메서드에 액세스
미리보기의 학생 그룹 메서드에 액세스하려면 다음 단계를 따라야 합니다.
- 개발자 프리뷰 프로그램 (DPP)에 참여합니다.
- 프리뷰 기능에 액세스하도록 클라이언트 라이브러리를 설정합니다. DPP의 메서드는 표준 클라이언트 라이브러리 및 표준 HTTP 요청에 노출되지 않습니다. DPP에 가입하면 특정 프로그래밍 언어의 학생 그룹 클라이언트 라이브러리에 액세스하여 다운로드할 수 있습니다. 선택한 클라이언트 라이브러리를 미리보기 버전 및 라벨로 설정하는 방법을 알아보려면 액세스 미리보기 API 페이지를 참고하세요.
- API 요청 시 미리보기 버전 및 미리보기 라벨을 설정합니다. 학생 그룹 메서드의 경우 미리보기 버전은
V1_20250630_PREVIEW이고 미리보기 라벨은DEVELOPER_PREVIEW입니다. 미리보기 버전이 포함된 API 요청의 예는 학생 그룹 관리 섹션에서 확인할 수 있습니다.
라이선스 및 자격 요건
수업에서 학생 그룹을 만들거나 수정 또는 삭제하고 학생 그룹에서 회원을 추가하거나 삭제하려면 다음 조건을 충족해야 합니다.
- 요청을 제출하는 사용자는 수업의 교사 또는 도메인의 관리자여야 합니다.
- 요청을 제출하는 사용자에게 Google Workspace for Education Plus 라이선스가 할당되어 있어야 합니다.
- 강의 소유자에게 Google Workspace for Education Plus 라이선스가 할당되어 있어야 합니다.
학생 그룹 및 구성원 읽기
수업의 관리자와 교사는 할당된 라이선스와 관계없이 학생 그룹 데이터를 읽을 수 있습니다. 즉, 과정의 모든 관리자 또는 교사를 대신하여 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가 포함됩니다.