Inizia a utilizzare le griglie

Un rubric è un modello che gli insegnanti possono utilizzare per valutare gli studenti contenuti inviati. L'API Classroom ti consente di agire per conto del l'insegnante per gestire queste griglie.

Figura 1. Visualizzazione di una griglia di esempio su un compito di Classroom.

Questa guida illustra i concetti e le funzionalità di base dell'API Rubrics. Consulta in questi articoli del Centro assistenza per saperne di più sulle struttura di una griglia e come la griglia la valutazione viene eseguita nell'interfaccia utente di Classroom.

Prerequisiti

Questa guida presuppone che tu abbia quanto segue:

• Python 3.8.6 o successivo
• Lo strumento di gestione dei pacchetti pip
• Un progetto Google Cloud.
• Un account Google Workspace for Education con Google Classroom. attivata.
• Un corso di prova con almeno un account studente di prova. Se non disponi di un di Classroom che puoi usare per i test, crearne uno nella UI e aggiungi uno studente di prova.

Autorizzare le credenziali per un'applicazione desktop

Per eseguire l'autenticazione 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 singola app ai server OAuth di Google. Se la tua app viene eseguita su più piattaforme, devi creare un ID cliente distinto per ogni piattaforma.

1. Vai alla pagina Credenziali di Google Cloud nella 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 è mostrato nella console Google Cloud. Ad esempio, "Client anteprima griglie".
5. Fai clic su Crea. Viene visualizzata la schermata di creazione del client OAuth, che mostra la nuova ID client e client secret.
6. Fai clic su Scarica JSON e poi su OK. La credenziale appena creata viene visualizzato negli ID client OAuth 2.0.
7. Salva il file JSON scaricato come credentials.json e sposta il file in nella directory di lavoro.
8. Fai clic su Crea credenziali > Chiave API e prendi nota della chiave API.

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

Configura gli ambiti OAuth

A seconda degli ambiti OAuth esistenti del progetto, potrebbe essere necessario configurare gli ambiti delle aggiunte.

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 scoprire di più, consulta Configurare la schermata per il consenso OAuth altro ancora.

L'ambito classroom.coursework.students consente l'accesso in lettura e scrittura a le griglie (oltre all'accesso a CourseWork) e l'ambito classroom.courses permette di leggere e scrivere corsi.

Gli ambiti richiesti per un determinato metodo sono elencati nella documentazione di riferimento per il 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 Google per le API. Le griglie non sono menzionate qui poiché l'API è ancora in anteprima.

Configura l'esempio

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

Nota: i campi e i metodi correlati alle griglie non vengono esposti nel client standard librerie perché Griglie CRUD è nell'anteprima per gli sviluppatori. Nell'esempio che segue specifica l'etichetta DEVELOPER_PREVIEW durante la generazione della libreria per abilitare dell'esposizione. Per scoprire di più sull'utilizzo delle API di anteprima, consulta Accedere alle API di anteprima. con le librerie client.

Crea un file denominato main.py che crea la libreria client e autorizza la 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. Viene richiesto di eseguire l'accesso per il consenso agli ambiti OAuth.

Crea un'assegnazione

Una griglia è associata a un compito, o CourseWork, ed è nel contesto di questo CourseWork. Le griglie possono essere create solo da nel progetto Google Cloud che ha creato l'elemento CourseWork padre. Ai fini di questa guida, crea un nuovo compito CourseWork con uno script.

Aggiungi il seguente codice 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 creare una nuova assegnazione di esempio e recuperare coursework_id:

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 griglie CRUD operazioni.

Ora in Classroom dovresti avere un file CourseWork di esempio.

Figura 2. Visualizzazione di un compito di esempio in Classroom.

Creare una griglia

A questo punto puoi iniziare a gestire le griglie.

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

Nota: poiché le griglie CRUD è nell'anteprima per gli sviluppatori, le chiamate al servizio per le griglie restituiscono un errore se non è specificato un valore previewVersion appropriato. La nell'esempio seguente e per tutte le chiamate successive relative alle griglie, imposta il previewVersion su V1_20231110_PREVIEW. Consulta Accedere alle API di anteprima per scopri di più su come specificare le versioni e la roadmap per scoprire quali versioni sono supportate.

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

Poi aggiorna ed esegui main.py per creare la griglia di esempio, utilizzando Course e CourseWork ID della versione precedente:

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

Nota: osserva che la griglia restituita contiene il valore previewVersion utilizzato nella CREA chiamata. Le risorse associate a una chiamata al metodo di anteprima contengono anche previewVersion utilizzato nella chiamata come campo di sola lettura, per aiutarti a comprendere la versione in uso.

Alcuni punti riguardo alla rappresentazione della griglia:

• Il criterio e l'ordine dei livelli sono riportati nell'interfaccia utente di Classroom.
• I livelli con punteggi (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 possono riordinare i criteri e i livelli con punteggi (ma non senza punteggio livelli) nell'interfaccia utente e questo cambia l'ordine nei dati.

Per ulteriori avvertenze sulla struttura delle griglie, consulta i limiti.

Tornando alla UI, dovresti vedere la griglia associata al compito.

Figura 3. Visualizzazione di una griglia di esempio su un compito di Classroom.

Leggere una griglia

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

Per ogni compito può essere presente al massimo una griglia, pertanto List potrebbe sembrare non intuitiva, ma è utile se non hai già l'ID griglia. Se ci sono non è nessuna griglia associata 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 griglia 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 griglia per i passaggi successivi.

Get funziona bene se hai l'ID griglia. Utilizzo 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 errore 404 in assenza di una griglia.

Aggiornare una griglia

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

Le regole di aggiornamento sono le seguenti:

1. Vengono presi in considerazione i criteri o i livelli aggiunti senza un ID addizioni.
2. Vengono considerati criteri o livelli mancanti rispetto alla versione precedente eliminazioni.
3. Vengono presi in considerazione criteri o livelli con un ID esistente ma con dati modificati modifiche. Le proprietà non modificate vengono lasciate invariate.
4. Vengono presi in considerazione criteri o livelli forniti con ID nuovi o sconosciuti errori.
5. L'ordine dei nuovi criteri e livelli viene considerato come ordine della nuova UI (con le limitazioni sopra citate).

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 viene specificato per la modifica con un updateMask

Quindi modifica main.py per apportare una modifica per ciascuno degli aggiornamenti sopra menzionati regole:

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

Ora le modifiche dovrebbero essere visibili all'insegnante in Classroom.

Figura 4. Visualizzazione della griglia aggiornata.

Nota: queste regole di modifica diventano più limitate una volta iniziata la valutazione.

Visualizzare i compiti valutati con griglia

Al momento i compiti degli studenti non possono essere valutati con una griglia tramite l'API, possono leggere i voti in griglia per i contenuti che sono stati valutati con una griglia nell'interfaccia utente di Classroom.

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.

Figura 5. Visualizzazione della griglia per l'insegnante durante la valutazione.

Suggerimento: questo è un buon momento per acquisire familiarità con la flessibilità offerta dell'insegnante quando usa una griglia. Ad esempio, osserva che l'insegnante può sostituisce i punti del criterio dei livelli scelti, il punteggio totale del compito calcolati in base ai criteri, saltando del tutto la scelta dei livelli. Consulta limitazioni.

I commissioni degli studenti valutati con una griglia hanno due nuove proprietà: draftRubricGrades e assignedRubricGrades, che rappresentano punti e livelli scelti dall'insegnante durante la bozza e la valutazione assegnata stati, rispettivamente.

Inoltre, i compiti degli studenti a cui è associata una griglia contengono un rubricId ancor prima della valutazione. Rappresenta l'ultima griglia associata a CourseWork, e questo valore potrebbe cambiare se gli insegnanti eliminano e ricreano un griglia di base.

Puoi utilizzare le versioni esistenti di studentSubmissions.Get e studentSubmissions.List metodi per visualizzare i contenuti valutati.

Avviso: i campi rubricId, draftRubricGrades e assignedRubricGrades non vengono esposti per impostazione predefinita nell'API Classroom e sono accessibili solo nell'anteprima per gli sviluppatori. Ciò significa che devi impostare un valore previewVersion per recuperarle. A differenza del servizio per le griglie, le chiamate servizio di invio non restituisce errori quando la versione viene omessa. Questi campi sono annotate come tali nella documentazione di riferimento.

Aggiungi la seguente funzione a main.py per elencare i lavori consegnati 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 provenire livello selezionato, ma anche l'insegnante potrebbe averlo sovrascritto.
• Il levelId del livello scelto per ogni criterio. Se l'insegnante non scegliere un livello, ma sono comunque assegnati punti per il criterio, questo campo non è presente.

Questi elenchi contengono solo le voci relative ai criteri in cui un insegnante selezionato un livello o dei set-point. Ad esempio, se un insegnante sceglie di mostrare solo interagiscono con un criterio durante la valutazione, draftRubricGrades e assignedRubricGrades avrebbe un solo elemento, anche se la griglia ne ha molti criteri.

Suggerimento: questo è un buon momento per sperimentare con queste proprietà. Puoi rivalutare il compito nell'UI di Classroom inviandolo di nuovo come studente, quindi passare all'account insegnante e scegliere Cancella, creando nuovi selezioni e restituire il compito. Fatto questo, puoi esegui nuovamente lo script Python per vedere le modifiche nell'oggetto inviato dallo studente.

Eliminare una griglia

Una griglia può essere eliminata con una richiesta Delete standard. Il seguente codice mostra una funzione di esempio per la completezza, ma poiché la valutazione ha già 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 su Google Fogli di lavoro che possono essere riutilizzati dagli insegnanti.

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

Nota: per creare (o aggiornare) una griglia dal foglio di lavoro di un utente, l'applicazione deve richiedere https://www.googleapis.com/auth/spreadsheets.readonly o https://www.googleapis.com/auth/spreadsheets nell'ambito. Puoi farlo aggiungendo uno degli ambiti al tuo progetto, come descritto nella sezione su configurazione di OAuth e aggiornamento della variabile SCOPES in main.py per includere l'ambito di applicazione. Elimina token.json per poter autorizzare di nuovo i nuovi ambiti la prossima volta che eseguirai main.py. Tieni presente che gli ambiti spreadsheets sono considerati sensibili e potrebbero richiedere la verifica della tua richiesta.

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 rilevi problemi o hai dei commenti, condividi il tuo feedback.