Creare e gestire gruppi di studenti

Puoi utilizzare i gruppi di studenti per organizzare gli studenti in gruppi specifici per migliorare le esperienze di insegnamento, ad esempio compiti mirati e attività collaborative. Utilizza l'API Classroom per creare, modificare e leggere i gruppi di studenti all'interno di un corso per conto di amministratori e insegnanti.

Puoi creare, aggiornare, eliminare e leggere i gruppi di studenti utilizzando i seguenti metodi:

Puoi anche aggiungere, rimuovere e leggere i membri all'interno di un gruppo di studenti utilizzando i seguenti metodi:

Accedere ai metodi dei gruppi di studenti nel programma di anteprima per gli sviluppatori

Per accedere ai metodi dei gruppi di studenti in anteprima, devi:

  • Partecipa al Programma Anteprima per sviluppatori (DPP).
  • Configura la libreria client per accedere alle funzionalità di anteprima. I metodi in DPP non sono esposti nelle librerie client standard e nelle richieste HTTP standard. Dopo aver aderito correttamente al programma DPP, puoi accedere e scaricare le librerie client dei gruppi di studenti per linguaggi di programmazione specifici. Consulta la pagina Accedere alle API di anteprima per scoprire come configurare la libreria client che preferisci con una versione e un'etichetta di anteprima.
  • Imposta la versione di anteprima e l'etichetta di anteprima quando effettui richieste API. Per i metodi dei gruppi di studenti, la versione di anteprima è V1_20250630_PREVIEW e l'etichetta di anteprima è DEVELOPER_PREVIEW. Puoi trovare esempi di richieste API con la versione di anteprima nella sezione Gestisci gruppi di studenti.

Requisiti di idoneità e licenza

Per creare, modificare o eliminare gruppi di studenti in un corso e aggiungere o rimuovere membri dai gruppi di studenti, devono essere soddisfatte le seguenti condizioni:

Lettura dei gruppi di studenti e dei relativi membri

Gli amministratori e gli insegnanti di un corso possono leggere i dati dei gruppi di studenti indipendentemente dalla licenza assegnata. Ciò significa che le richieste agli endpoint ListStudentGroups e ListStudentGroupMembers sono consentite per conto di qualsiasi amministratore o insegnante di un corso.

Prerequisiti per l'esempio di codice

Questa guida fornisce esempi di codice in Python e presuppone che tu disponga di quanto segue:

  • Un progetto Google Cloud. Puoi configurarne uno seguendo le istruzioni riportate nella guida rapida di Python.
  • Sono stati aggiunti i seguenti ambiti alla schermata per il consenso OAuth del progetto:
    • https://www.googleapis.com/auth/classroom.rosters
    • https://www.googleapis.com/auth/classroom.rosters.readonly per gli endpoint di sola lettura.
  • Un ID di un corso in cui devono essere gestiti i gruppi di studenti. Il proprietario del corso deve disporre di una licenza Google Workspace for Education Plus.
  • Accesso alle credenziali di un insegnante o di un amministratore con una licenza Google Workspace for Education Plus.

Se hai seguito la guida rapida di Python come punto di partenza, modifica il servizio Classroom per accedere ai metodi di anteprima.

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

Verificare l'idoneità dell'utente

L'API Classroom fornisce l'endpoint userProfiles.checkUserCapability per aiutarti a determinare in modo proattivo se un utente è in grado di creare e modificare i gruppi di studenti e i relativi membri.

L'endpoint userProfiles.checkUserCapability valuta solo se un utente è idoneo a utilizzare una determinata funzionalità, ad esempio la modifica dei gruppi di studenti. Non offre informazioni sul ruolo del corso. Ad esempio, anche se un utente dispone della funzionalità CREATE_STUDENT_GROUP, se è uno studente del corso, una richiesta all'endpoint CreateStudentGroup non andrà a buon fine.

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

Gestisci i gruppi di studenti

I gruppi di studenti possono essere creati utilizzando l'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)

La risposta contiene l'id del gruppo di studenti appena creato, l'courseId e l'title del gruppo di studenti.

Il gruppo di studenti id può essere utilizzato per aggiornare o eliminare il gruppo di singoli studenti.

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)

Puoi recuperare i gruppi di studenti all'interno di un corso utilizzando l'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")

Gestire i membri dei gruppi di studenti

Una volta creato il gruppo di studenti, puoi aggiungervi membri.

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 vuoi rimuovere un membro da un gruppo di studenti, invia una richiesta come la seguente:

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)

Puoi leggere i membri di un gruppo effettuando la seguente richiesta:

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

Ogni risorsa StudentGroupMember include courseId, studentGroupId e userId del membro del gruppo.

Indietro
Creare e gestire tutori