Inizia a utilizzare le griglie

Un rubric è un modello che gli insegnanti possono utilizzare per valutare i compiti inviati dagli studenti. L'API Classroom consente di gestire queste griglie per conto dell'insegnante.

Visualizzazione di una griglia nell'interfaccia utente di Classroom Figura 1. Visualizzazione di una griglia di esempio in un compito di Classroom.

Questa guida illustra i concetti e le funzionalità di base dell'API Rubrics. Consulta questi articoli del Centro assistenza per scoprire la struttura generale di una rubrica e come viene eseguita la valutazione con la rubrica nell'interfaccia utente di Classroom.

Prerequisiti

Questa guida presuppone che tu disponga di quanto segue:

Autorizzare le credenziali per un'applicazione desktop

Per autenticarti come utente finale e accedere ai dati utente nella tua app, devi creare uno o più ID client OAuth 2.0. L'ID client viene utilizzato per identificare una singola app nei server OAuth di Google. Se l'app viene eseguita su più piattaforme, devi creare un ID client separato per ogni piattaforma.

  1. Vai alla pagina Credenziali di Google Cloud nella console Google Cloud.
  2. Fai clic su Crea credenziali > ID client OAuth.
  3. Fai clic su Tipo di applicazione > App desktop.
  4. Nel campo Nome, digita un nome per la credenziale. Questo nome viene visualizzato solo nella console Google Cloud. Ad esempio, "Client di anteprima delle rubriche".
  5. Fai clic su Crea. Viene visualizzata la schermata del client OAuth creato, che mostra il nuovo ID client e il nuovo client secret.
  6. Fai clic su Scarica JSON e poi su OK. Le credenziali appena create vengono visualizzate negli ID client OAuth 2.0.
  7. Salva il file JSON scaricato come credentials.json e spostalo nella directory di lavoro.
  8. Fai clic su Crea credenziali > Chiave API e prendi nota della chiave API.

Per saperne di più, consulta Creare le credenziali di accesso.

Configurare gli ambiti OAuth

A seconda degli ambiti OAuth esistenti del progetto, potrebbe essere necessario configurare altri ambiti.

  1. Vai alla schermata per il consenso OAuth.
  2. Fai clic su Modifica app > Salva e continua per accedere alla schermata Ambiti.
  3. Fai clic su Aggiungi o rimuovi ambiti.
  4. Aggiungi i seguenti ambiti, se non li hai già:
    • https://www.googleapis.com/auth/classroom.coursework.students
    • https://www.googleapis.com/auth/classroom.courses
  5. Quindi, fai clic su Aggiorna > Salva e continua > Salva e continua > Torna alla dashboard.

Per saperne di più, consulta Configurare la schermata per il consenso OAuth.

L'ambito classroom.coursework.students consente l'accesso in lettura e scrittura alle rubriche (oltre all'accesso a CourseWork), mentre l'ambito classroom.courses consente di leggere e scrivere i corsi.

Gli ambiti richiesti per un determinato metodo sono elencati nella documentazione di riferimento del metodo. Vedi gli ambiti di autorizzazione di courses.courseWork.rubrics.create come esempio. Puoi visualizzare tutti gli ambiti di Classroom in Ambiti OAuth 2.0 per le API di Google. Le rubriche non sono menzionate qui perché l'API è ancora in versione beta.

Configura il Sample

Nella directory di lavoro, installa la libreria client di Google per Python:

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Crea un file denominato main.py che genera la libreria client e autorizza l'utente, utilizzando la tua chiave API al posto di YOUR_API_KEY:

import json
import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
SCOPES = ['https://www.googleapis.com/auth/classroom.courses',
          'https://www.googleapis.com/auth/classroom.coursework.students']

def build_authenticated_service(api_key):
    """Builds the Classroom service."""
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run.
        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    try:
        # Build the Classroom service.
        service = build(
            serviceName="classroom",
            version="v1",
            credentials=creds,
            discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key={api_key}")

        return service

    except HttpError as error:
        print('An error occurred: %s' % error)

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

Esegui lo script utilizzando python main.py. Ti verrà chiesto di accedere e fornire il consenso agli ambiti OAuth.

Crea un'assegnazione

Una griglia è associata a un compito, o CourseWork, ed è significativa solo nel contesto di quell'elemento (CourseWork). Le rubriche possono essere create solo dal progetto Google Cloud che ha creato l'elemento CourseWork principale. Ai fini di questa guida, crea un nuovo compito CourseWork con uno script.

Aggiungi quanto segue a main.py:

def get_latest_course(service):
    """Retrieves the last created course."""
    try:
        response = service.courses().list(pageSize=1).execute()
        courses = response.get("courses", [])
        if not courses:
            print("No courses found. Did you remember to create one in the UI?")
            return
        course = courses[0]
        return course

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

def create_coursework(service, course_id):
    """Creates and returns a sample coursework."""
    try:
        coursework = {
            "title": "Romeo and Juliet analysis.",
            "description": """Write a paper arguing that Romeo and Juliet were
                                time travelers from the future.""",
            "workType": "ASSIGNMENT",
            "state": "PUBLISHED",
        }
        coursework = service.courses().courseWork().create(
            courseId=course_id, body=coursework).execute()
        return coursework

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Ora aggiorna main.py per recuperare il course_id della classe di prova che hai appena creato, creare un nuovo compito di esempio e recuperare il coursework_id del compito:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    course = get_latest_course(service)
    course_id = course.get("id")
    course_name = course.get("name")
    print(f"'{course_name}' course ID: {course_id}")

    coursework = create_coursework(service, course_id)
    coursework_id = coursework.get("id")
    print(f"Assignment created with ID {coursework_id}")

    #TODO(developer): Save the printed course and coursework IDs.

Salva course_id e coursework_id. Sono necessari per tutte le operazioni CRUD delle rubriche.

Ora dovresti avere un Sample CourseWork in Classroom.

Visualizzazione di un compito nell'UI di Classroom Figura 2. Visualizzazione di un compito di esempio in Classroom.

Creare una griglia

Ora puoi iniziare a gestire le rubriche.

È possibile creare una griglia su un CourseWork con una chiamata Create contenente l'oggetto griglia completa, in cui le proprietà ID per criteri e livelli sono omesse (sono generate al momento della creazione).

Aggiungi la seguente funzione a main.py:

def create_rubric(service, course_id, coursework_id):
    """Creates an example rubric on a coursework."""
    try:
        body = {
            "criteria": [
                {
                    "title": "Argument",
                    "description": "How well structured your argument is.",
                    "levels": [
                        {"title": "Convincing",
                         "description": "A compelling case is made.", "points": 30},
                        {"title": "Passable",
                         "description": "Missing some evidence.", "points": 20},
                        {"title": "Needs Work",
                         "description": "Not enough strong evidence..", "points": 0},
                    ]
                },
                {
                    "title": "Spelling",
                    "description": "How well you spelled all the words.",
                    "levels": [
                        {"title": "Perfect",
                         "description": "No mistakes.", "points": 20},
                        {"title": "Great",
                         "description": "A mistake or two.", "points": 15},
                        {"title": "Needs Work",
                         "description": "Many mistakes.", "points": 5},
                    ]
                },
                {
                    "title": "Grammar",
                    "description": "How grammatically correct your sentences are.",
                    "levels": [
                        {"title": "Perfect",
                         "description": "No mistakes.", "points": 20},
                        {"title": "Great",
                         "description": "A mistake or two.", "points": 15},
                        {"title": "Needs Work",
                         "description": "Many mistakes.", "points": 5},
                    ]
                },
            ]
        }

        rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id, courseWorkId=coursework_id, body=body,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()
        print(f"Rubric created with ID {rubric.get('id')}")
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Aggiorna ed esegui main.py per creare la rubrica di esempio utilizzando gli ID Course e CourseWork precedenti:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(rubric, indent=4))

Alcuni punti riguardo alla rappresentazione della griglia:

  • L'ordine dei criteri e dei livelli è riportato nell'interfaccia utente di Classroom.
  • I livelli con punteggio (quelli con la proprietà points) devono essere ordinati in base ai punti in ordine crescente o decrescente (non possono essere ordinati in modo casuale).
  • Gli insegnanti sono in grado di riordinare i criteri e i livelli con punteggi (ma non i livelli senza punteggio) nell'interfaccia utente, cambiando l'ordine nei dati.

Per ulteriori avvertenze sulla struttura delle griglie, consulta le limitazioni.

Tornando all'interfaccia utente, dovresti vedere la rubrica nel compito.

Visualizzazione di una griglia nell'interfaccia utente di Classroom Figura 3. Visualizzazione di una griglia di esempio in un compito di Classroom.

Leggere una griglia

Le rubriche possono essere lette con i metodi standard List e Get.

Per un compito può esserci al massimo una griglia, quindi List può sembrare non intuitivo, ma è utile se non hai già l'ID griglia. Se non è associata alcuna rubrica a un CourseWork, la risposta List è vuota.

Aggiungi la seguente funzione a main.py:

def get_rubric(service, course_id, coursework_id):
    """
    Get the rubric on a coursework. There can only be at most one.
    Returns null if there is no rubric.
    """
    try:
        response = service.courses().courseWork().rubrics().list(
            courseId=course_id, courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()

        rubrics = response.get("rubrics", [])
        if not rubrics:
            print("No rubric found for this assignment.")
            return
        rubric = rubrics[0]
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Aggiorna ed esegui main.py per recuperare la rubrica che hai aggiunto:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(rubric, indent=4))

    #TODO(developer): Save the printed rubric ID.

Prendi nota della proprietà id nella rubrica per i passaggi successivi.

Get funziona bene quando hai l'ID rubrica. L'uso di Get nella funzione potrebbe avere il seguente aspetto:

def get_rubric(service, course_id, coursework_id, rubric_id):
    """
    Get the rubric on a coursework. There can only be at most one.
    Returns a 404 if there is no rubric.
    """
    try:
        rubric = service.courses().courseWork().rubrics().get(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Questa implementazione restituisce un codice 404 se non è presente una rubrica.

Aggiornare una griglia

Gli aggiornamenti a una griglia vengono eseguiti con le chiamate a Patch. A causa della complessa struttura di una griglia, gli aggiornamenti devono essere eseguiti con un pattern di lettura, modifica e scrittura, in cui l'intera proprietà criteria viene sostituita.

Le regole di aggiornamento sono le seguenti:

  1. I criteri o i livelli aggiunti senza un ID sono considerati aggiunte.
  2. I criteri o i livelli mancanti rispetto a prima sono considerati eliminazioni.
  3. I criteri o i livelli con un ID esistente, ma con dati modificati sono considerati modifiche. Le proprietà non modificate rimangono invariate.
  4. I criteri o i livelli forniti con ID nuovi o sconosciuti sono considerati errori.
  5. L'ordine dei nuovi criteri e livelli è considerato il nuovo ordine dell'interfaccia utente (con le limitazioni sopra indicate).

Aggiungi una funzione per aggiornare una griglia:

def update_rubric(service, course_id, coursework_id, rubric_id, body):
    """
    Updates the rubric on a coursework.
    """
    try:
        rubric = service.courses().courseWork().rubrics().patch(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            body=body,
            updateMask='criteria',
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

In questo esempio, il campo criteria è specificato per la modifica con un updateMask.

Poi modifica main.py per apportare una modifica a ciascuna delle regole di aggiornamento sopra indicate:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    # Get the latest rubric.
    rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    criteria = rubric.get("criteria")
    """
    The "criteria" property should look like this:
    [
        {
            "id": "NkEyMdMyMzM2Nxkw",
            "title": "Argument",
            "description": "How well structured your argument is.",
            "levels": [
                {
                    "id": "NkEyMdMyMzM2Nxkx",
                    "title": "Convincing",
                    "description": "A compelling case is made.",
                    "points": 30
                },
                {
                    "id": "NkEyMdMyMzM2Nxky",
                    "title": "Passable",
                    "description": "Missing some evidence.",
                    "points": 20
                },
                {
                    "id": "NkEyMdMyMzM2Nxkz",
                    "title": "Needs Work",
                    "description": "Not enough strong evidence..",
                    "points": 0
                }
            ]
        },
        {
            "id": "NkEyMdMyMzM2Nxk0",
            "title": "Spelling",
            "description": "How well you spelled all the words.",
            "levels": [...]
        },
        {
            "id": "NkEyMdMyMzM2Nxk4",
            "title": "Grammar",
            "description": "How grammatically correct your sentences are.",
            "levels": [...]
        }
    ]
    """

    # Make edits. This example will make one of each type of change.

    # Add a new level to the first criteria. Levels must remain sorted by
    # points.
    new_level = {
        "title": "Profound",
        "description": "Truly unique insight.",
        "points": 50
    }
    criteria[0]["levels"].insert(0, new_level)

    # Remove the last criteria.
    del criteria[-1]

    # Update the criteria titles with numeric prefixes.
    for index, criterion in enumerate(criteria):
        criterion["title"] = f"{index}: {criterion['title']}"

    # Resort the levels from descending to ascending points.
    for criterion in criteria:
        criterion["levels"].sort(key=lambda level: level["points"])

    # Update the rubric with a patch call.
    new_rubric = update_rubric(
        service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID, YOUR_RUBRIC_ID, rubric)

    print(json.dumps(new_rubric, indent=4))

Le modifiche ora dovrebbero essere visibili per l'insegnante in Classroom.

Visualizzazione di una griglia aggiornata nell'interfaccia utente di Classroom Figura 4. Visualizzazione della rubrica aggiornata.

Visualizzare i contenuti inviati valutati con una griglia

Al momento, i compiti degli studenti non possono essere valutati con una griglia tramite l'API, ma nella UI di Classroom è possibile leggere i voti in griglia per i compiti che sono stati valutati con una griglia.

Come studente, nell'interfaccia utente di Classroom, completa e consegna il compito di esempio. Poi, in qualità di insegnante, valuta manualmente il compito utilizzando la griglia.

Visualizzazione di un voto con griglia nella UI di Classroom Figura 5. Visualizzazione della griglia da parte dell'insegnante durante la valutazione.

I commissioni degli studenti valutati con una griglia hanno due nuove proprietà: draftRubricGrades e assignedRubricGrades, che rappresentano i punti e i livelli scelti dall'insegnante durante lo stato di valutazione provvisorio e assegnato.

Inoltre, i compiti inviati dagli studenti con una griglia associata contengono un campo rubricId anche prima della valutazione. Rappresenta la rubrica più recente associata al compito CourseWork e questo valore potrebbe cambiare se gli insegnanti eliminano e ricreano una rubrica.

Puoi utilizzare i metodi esistenti studentSubmissions.Get e studentSubmissions.List per visualizzare i contenuti inviati con voto.

Aggiungi la seguente funzione a main.py per elencare i contenuti inviati dagli studenti:

def get_latest_submission(service, course_id, coursework_id):
    """Retrieves the last submission for an assignment."""
    try:
        response = service.courses().courseWork().studentSubmissions().list(
            courseId = course_id,
            courseWorkId = coursework_id,
            pageSize=1,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()
        submissions = response.get("studentSubmissions", [])
        if not submissions:
            print(
                """No submissions found. Did you remember to turn in and grade
                   the assignment in the UI?""")
            return
        submission = submissions[0]
        return submission

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Quindi aggiorna ed esegui main.py per visualizzare i voti dei contenuti inviati.

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    submission = get_latest_submission(
        service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(submission, indent=4))

draftRubricGrades e assignedRubricGrades contengono:

  • Il criterionId dei criteri della griglia corrispondenti.
  • Il valore points assegnato dall'insegnante per ogni criterio. Potrebbe trattarsi del livello selezionato, ma anche l'insegnante potrebbe aver sovrascritto questo livello.
  • Il levelId del livello scelto per ciascun criterio. Se l'insegnante non ha scelto un livello, ma ha comunque assegnato punti per il criterio, questo campo non è presente.

Questi elenchi contengono solo le voci per i criteri in cui un insegnante ha selezionato un livello o impostato dei punti. Ad esempio, se un insegnante sceglie di interagire con un solo criterio durante la valutazione, draftRubricGrades e assignedRubricGrades avranno un solo elemento, anche se la griglia ha molti criteri.

Eliminare una griglia

Una rubrica può essere eliminata con una richiesta Delete standard. Il codice seguente mostra una funzione di esempio per completezza, ma poiché la valutazione è già iniziata, non puoi eliminare la griglia corrente:

def delete_rubric(service, course_id, coursework_id, rubric_id):
    """Deletes the rubric on a coursework."""
    try:
        service.courses().courseWork().rubrics().delete(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Esportare e importare le griglie

Le griglie possono essere esportate manualmente in Fogli Google per essere riutilizzate dagli insegnanti.

Oltre a specificare i criteri della griglia nel codice, è possibile creare e aggiornare le griglie da questi fogli esportati specificando sourceSpreadsheetId nel corpo della griglia anziché criteria:

def create_rubric_from_sheet(service, course_id, coursework_id, sheet_id):
    """Creates an example rubric on a coursework."""
    try:
        body = {
            "sourceSpreadsheetId": sheet_id
        }

        rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id, courseWorkId=coursework_id, body=body,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()

        print(f"Rubric created with ID {rubric.get('id')}")
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Feedback

Se riscontri problemi o hai suggerimenti, condividi il tuo feedback.