Membuat dan mengelola grup siswa

Anda dapat menggunakan grup siswa untuk mengelompokkan siswa ke dalam grup tertentu untuk meningkatkan pengalaman mengajar, seperti tugas yang ditargetkan dan aktivitas kolaboratif. Gunakan Classroom API untuk membuat, mengubah, dan membaca grup siswa dalam kursus atas nama administrator dan pengajar.

Anda dapat membuat, memperbarui, menghapus, dan membaca grup siswa menggunakan metode berikut:

• CreateStudentGroup
• PatchStudentGroup
• DeleteStudentGroup
• ListStudentGroups

Anda juga dapat menambahkan, menghapus, dan membaca anggota dalam grup siswa menggunakan metode berikut:

• CreateStudentGroupMember
• DeleteStudentGroupMember
• ListStudentGroupMembers

Mengakses metode grup siswa dalam Program Pratinjau Developer

Untuk mengakses metode grup siswa dalam pratinjau, Anda harus melakukan hal berikut:

• Bergabung dengan Program Pratinjau Developer (DPP).
• Siapkan library klien Anda untuk mengakses fitur pratinjau. Metode dalam DPP tidak diekspos di library klien standar dan permintaan HTTP standar. Setelah berhasil bergabung dengan DPP, Anda dapat mengakses dan mendownload library klien grup siswa untuk bahasa pemrograman tertentu. Lihat halaman Akses API pratinjau untuk mempelajari cara menyiapkan library klien pilihan Anda dengan versi dan label pratinjau.
• Tetapkan versi pratinjau dan label pratinjau saat membuat permintaan API. Untuk metode grup siswa, versi pratinjau adalah V1_20250630_PREVIEW dan label pratinjau adalah DEVELOPER_PREVIEW. Anda dapat menemukan contoh permintaan API dengan versi pratinjau di bagian Mengelola grup siswa.

Persyaratan pemberian lisensi dan kelayakan

Untuk membuat, mengubah, atau menghapus grup siswa dalam kursus dan menambahkan atau menghapus anggota dari grup siswa, kondisi berikut harus dipenuhi:

• Pengguna yang membuat permintaan harus menjadi pengajar dalam kursus atau administrator domain.
• Pengguna yang membuat permintaan harus memiliki lisensi Google Workspace for Education Plus yang ditetapkan untuknya.
• Pemilik kursus harus memiliki lisensi Google Workspace for Education Plus yang ditetapkan kepadanya.

Membaca grup siswa dan anggotanya

Administrator dan pengajar kursus dapat membaca data grup siswa terlepas dari lisensi yang ditetapkan kepada mereka. Artinya, permintaan ke endpoint ListStudentGroups dan ListStudentGroupMembers diizinkan atas nama administrator atau pengajar mana pun dalam kursus.

Prasyarat contoh kode

Panduan ini memberikan contoh kode dalam Python, dan mengasumsikan bahwa Anda memiliki hal berikut:

• Project Google Cloud. Anda dapat menyiapkannya dengan mengikuti petunjuk di Panduan memulai cepat Python.
• Menambahkan cakupan berikut ke layar izin OAuth project Anda:
  • https://www.googleapis.com/auth/classroom.rosters
  • https://www.googleapis.com/auth/classroom.rosters.readonly untuk endpoint hanya baca.
• ID kursus tempat grup siswa harus dikelola. Pemilik kursus harus memiliki lisensi Google Workspace for Education Plus.
• Akses ke kredensial pengajar atau administrator dengan lisensi Google Workspace for Education Plus.

Jika Anda mengikuti panduan memulai Python sebagai titik awal, ubah layanan Classroom untuk mengakses metode pratinjau.

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

Memeriksa kelayakan pengguna

Classroom API menyediakan endpoint userProfiles.checkUserCapability untuk membantu Anda secara proaktif menentukan apakah pengguna dapat membuat dan mengubah grup siswa dan anggotanya.

Endpoint userProfiles.checkUserCapability hanya mengevaluasi apakah pengguna memenuhi syarat untuk menggunakan kemampuan tertentu, seperti mengubah grup siswa. Tidak ada informasi tentang peran kursus. Misalnya, meskipun pengguna memiliki kemampuan CREATE_STUDENT_GROUP, jika dia adalah siswa dalam kursus, permintaan ke endpoint CreateStudentGroup tidak akan berhasil.

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

Mengelola grup siswa

Grup siswa dapat dibuat menggunakan endpoint CreateStudentGroup.

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)

Respons berisi id grup siswa yang baru dibuat, courseId, dan title grup siswa.

Grup siswa id dapat digunakan untuk memperbarui atau menghapus grup siswa individual.

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)

Anda dapat mengambil grup siswa dalam kursus menggunakan endpoint ListStudentGroups:

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

Mengelola anggota grup siswa

Setelah grup siswa berhasil dibuat, Anda dapat menambahkan anggota ke grup tersebut.

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)

Jika Anda ingin menghapus anggota dari grup siswa, buat permintaan seperti berikut:

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)

Anda dapat membaca anggota dalam grup dengan membuat permintaan berikut:

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

Setiap resource StudentGroupMember mencakup courseId, studentGroupId, dan userId anggota grup.