Criar e gerenciar grupos de estudantes

Use os grupos para organizar os estudantes em torno de atividades direcionadas, instruções diferenciadas, atividades colaborativas e muito mais. Use a API Classroom para criar, modificar e ler grupos de estudantes em um curso em nome de administradores e professores.

É possível criar, atualizar, excluir e ler grupos de estudantes usando os seguintes métodos:

Também é possível adicionar, remover e ler membros em um grupo de estudantes usando os seguintes métodos:

Acessar métodos de grupos de estudantes no Programa de prévia para desenvolvedores

Para acessar os métodos de grupos de estudantes em prévia, faça o seguinte:

Requisitos de licenciamento e qualificação

Para criar, modificar ou excluir grupos de estudantes em um curso e adicionar ou remover membros desses grupos, as seguintes condições precisam ser atendidas:

Leitura de grupos de estudantes e membros

Os administradores e professores de um curso podem ler os dados dos grupos de estudantes, independentemente da licença atribuída. Isso significa que as solicitações para os endpoints ListStudentGroups e ListStudentGroupMembers são permitidas em nome de qualquer administrador ou professor em um curso.

Pré-requisitos para exemplos de código

Este guia fornece exemplos de código em Python e pressupõe que você tenha o seguinte:

  • Um projeto do Google Cloud. Para configurar um, siga as instruções no Guia de início rápido do Python.
  • Adicione os seguintes escopos à tela de consentimento do OAuth do seu projeto:
    • https://www.googleapis.com/auth/classroom.rosters
    • https://www.googleapis.com/auth/classroom.rosters.readonly para endpoints somente leitura.
  • O ID de um curso em que os grupos de estudantes precisam ser gerenciados. O proprietário do curso precisa ter uma licença do Google Workspace for Education Plus.
  • Acesso às credenciais de um professor ou administrador com uma licença do Google Workspace for Education Plus.

Se você seguiu o início rápido do Python como ponto de partida, modifique o serviço do Google Sala de Aula para acessar os métodos de prévia.

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

Verificar a qualificação do usuário

A API Classroom oferece o endpoint userProfiles.checkUserCapability para ajudar você a determinar de forma proativa se um usuário pode criar e modificar grupos de estudantes e os membros deles.

O endpoint userProfiles.checkUserCapability avalia apenas se um usuário está qualificado para usar um determinado recurso, como modificar grupos de estudantes. Ela não oferece informações sobre a função no curso. Por exemplo, mesmo que um usuário tenha o recurso CREATE_STUDENT_GROUP, se ele for um estudante do curso, uma solicitação ao endpoint CreateStudentGroup não será bem-sucedida.

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

Gerenciar grupos de estudantes

Os grupos de estudantes podem ser criados usando o endpoint 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)

A resposta contém o id do grupo de estudantes recém-criado, o courseId e o title do grupo de estudantes.

O grupo de estudantes id pode ser usado para atualizar ou excluir o grupo de estudantes individual.

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)

É possível recuperar os grupos de estudantes em um curso usando o endpoint 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")

Gerenciar participantes de grupos de estudantes

Depois que o grupo de estudantes for criado, você poderá adicionar membros a ele.

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)

Se você quiser remover um membro de um grupo de estudantes, faça uma solicitação como a seguinte:

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)

Para ler os membros de um grupo, faça a seguinte solicitação:

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

Cada recurso StudentGroupMember inclui o courseId, studentGroupId e userId do membro do grupo.

Anterior
Criar e gerenciar responsáveis