Gestire i periodi di valutazione utilizzando l'API Classroom

Questa guida spiega come utilizzare gli endpoint dei periodi di valutazione nell'API Google Classroom.

Panoramica

I periodi di valutazione vengono creati per organizzare compiti, quiz e progetti in intervalli di date specifici. L'API Classroom consente agli sviluppatori di creare, modificare e leggere i periodi di valutazione in Classroom per conto di amministratori e insegnanti. Puoi anche utilizzare l'API Classroom per impostare i periodi di valutazione in Lavori del corso.

L'API Classroom offre due endpoint per leggere e scrivere le informazioni sui periodi di valutazione in un corso:

• GetGradingPeriodSettings: consente di leggere le impostazioni dei periodi di valutazione in un corso.
• UpdateGradingPeriodSettings: consente di gestire le impostazioni dei periodi di valutazione in un corso aggiungendo, modificando ed eliminando i periodi di valutazione e applicando i periodi di valutazione configurati a tutti i lavori del corso esistenti.

Requisiti di licenza ed idoneità

Modificare le impostazioni dei periodi di valutazione in un corso

Per creare, modificare o eliminare i periodi di valutazione in un corso utilizzando l'endpoint UpdateGradingPeriodSettings, devono essere soddisfatte le seguenti condizioni:

• L'utente che effettua la richiesta deve essere un insegnante del corso o un amministratore.
• All'utente che effettua la richiesta è stata assegnata una licenza Google Workspace for Education Plus.
• Al proprietario del corso è stata assegnata una licenza Google Workspace for Education Plus.

Leggere le impostazioni dei periodi di valutazione in un corso

Gli amministratori di dominio e gli insegnanti di un corso possono leggere le impostazioni dei periodi di valutazione indipendentemente dalla licenza assegnata. Ciò significa che le richieste all'endpoint GetGradingPeriodSettings sono consentite per conto di qualsiasi amministratore di dominio o insegnante.

Impostare un ID periodo di valutazione in Lavori del corso

Gli insegnanti di un corso possono includere gradingPeriodId quando creano o aggiornano i lavori del corso utilizzando l'API, indipendentemente dalla licenza assegnata.

Verificare l'idoneità di un utente a configurare i periodi di valutazione

Le richieste all'endpoint userProfiles.checkUserCapability sono consentite per conto di qualsiasi amministratore o insegnante. Utilizza questo endpoint per determinare se l'utente può modificare i periodi di valutazione.

Prerequisiti

Questa guida fornisce esempi di codice in Python e presuppone che tu abbia:

• Un progetto Google Cloud. Puoi configurarne uno seguendo le istruzioni della guida rapida di Python.
• Aggiunto i seguenti ambiti alla schermata per il consenso OAuth del progetto:
  • https://www.googleapis.com/auth/classroom.courses
  • https://www.googleapis.com/auth/classroom.coursework.students
• Un ID di un corso in cui devono essere modificati i periodi di valutazione. Il proprietario del corso deve avere 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. Per creare o modificare i lavori del corso, avrai bisogno delle credenziali di un insegnante. Gli amministratori non possono creare o modificare i lavori del corso se non sono insegnanti del corso.

Gestire la risorsa GradingPeriodSettings

La risorsa GradingPeriodSettings include un elenco di singoli GradingPeriods e un campo booleano denominato applyToExistingCoursework.

Assicurati che ogni singolo GradingPeriods nell'elenco soddisfi i seguenti requisiti:

• Titolo, data di inizio e data di fine: ogni periodo di valutazione deve avere un titolo, una data di inizio e una data di fine.
• Titolo univoco: ogni periodo di valutazione deve avere un titolo univoco che non corrisponda a nessun altro periodo di valutazione del corso.
• Date non sovrapposte: ogni periodo di valutazione non deve avere date di inizio o di fine che si sovrappongano ad altri periodi di valutazione del corso.
• Ordine cronologico: i periodi di valutazione devono essere elencati in ordine cronologico in base alle date di inizio e di fine.

A ogni periodo di valutazione verrà assegnato un identificatore assegnato dall'API Classroom al momento della creazione.

Il valore booleano applyToExistingCoursework è un'impostazione persistente che consente di organizzare i lavori del corso creati in precedenza in periodi di valutazione senza dover effettuare una chiamata API separata per modificare gradingPeriodId per ogni lavoro del corso. Se è impostato su True, Classroom imposterà automaticamente gradingPeriodId su tutti i lavori del corso esistenti se courseWork.dueDate rientra nelle date di inizio e di fine di un periodo di valutazione esistente. Se non è stata impostata una data di scadenza per i lavori del corso, Classroom utilizzerà courseWork.scheduledTime. Se nessuno dei due campi è presente o non esiste una corrispondenza all'interno delle date di inizio e di fine di un periodo di valutazione esistente, i lavori del corso non verranno associati a nessun periodo di valutazione.

Determinare se un utente può modificare le impostazioni dei periodi di valutazione in un corso

L'API Classroom fornisce l'endpoint userProfiles.checkUserCapability per aiutarti a determinare in modo proattivo se un utente è in grado di effettuare richieste all'endpoint UpdateGradingPeriodSettings.

def check_grading_periods_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        capability = classroom_service.userProfiles().checkUserCapability(
          userId="me",
          capability="UPDATE_GRADING_PERIOD_SETTINGS",
           # Required while the checkUserCapability method is available in the Developer Preview Program.
          previewVersion="V1_20240930_PREVIEW"
        ).execute()

        # Retrieve the `allowed` boolean from the response.
        if capability.get("allowed"):
          print("User is allowed to update grading period settings in the course.")
        else:
          print("User is not allowed to update grading period settings in the course.")
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Aggiungere periodi di valutazione

Ora che hai la certezza che l'utente è idoneo a modificare le impostazioni dei periodi di valutazione in un corso, puoi iniziare a inviare richieste all'endpoint UpdateGradingPeriodSettings. Qualsiasi modifica alla GradingPeriodSettings risorsa viene eseguita utilizzando l'endpoint UpdateGradingPeriodSettings sia che tu stia aggiungendo singoli periodi di valutazione , modificando i periodi di valutazione esistenti o eliminando un periodo di valutazione.

def create_grading_periods(classroom_service, course_id):
    """
    Create grading periods in a course and apply the grading periods
    to existing courseWork.
    """
    try:
        body = {
          "gradingPeriods": [
            {
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": True
        }
        gradingPeriodSettingsResponse = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body
        ).execute();

        print(f"Grading period settings updated.")
        return gradingPeriodSettingsResponse

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Leggere le impostazioni dei periodi di valutazione

GradingPeriodSettings vengono letti utilizzando l'endpoint GetGradingPeriodSettings. Qualsiasi utente, indipendentemente dalla licenza, può leggere le impostazioni dei periodi di valutazione in un corso.

def get_grading_period_settings(classroom_service, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom_service.courses().getGradingPeriodSettings(
          courseId=course_id).execute()
        return gradingPeriodSettings
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Aggiungere un singolo periodo di valutazione all'elenco

Gli aggiornamenti a un singolo periodo di valutazione devono essere eseguiti seguendo un pattern di lettura-modifica-scrittura. Ciò significa che dovresti:

1. Leggi l'elenco dei periodi di valutazione all'interno della risorsa GradingPeriodSettings utilizzando l'endpoint GetGradingPeriodSettings.
2. Apporta le modifiche scelte all'elenco dei periodi di valutazione.
3. Invia il nuovo elenco dei periodi di valutazione in una richiesta a UpdateGradingPeriodSettings.

Questo pattern ti aiuterà a garantire che i singoli titoli dei periodi di valutazione in un corso siano distinti e che non vi siano sovrapposizioni tra le date di inizio e di fine dei periodi di valutazione.

Tieni presente le seguenti regole per l'aggiornamento dell'elenco dei periodi di valutazione:

1. I periodi di valutazione aggiunti all'elenco senza un ID sono considerati aggiunte.
2. I periodi di valutazione mancanti nell'elenco sono considerati eliminazioni.
3. I periodi di valutazione con un ID esistente ma dati modificati sono considerati modifiche. Le proprietà non modificate vengono lasciate invariate.
4. I periodi di valutazione con ID nuovi o sconosciuti sono considerati errori.

def add_grading_period(classroom_service, course_id):
    """
    A new grading period is added to the list, but it is not applied to existing courseWork.
    """
    try:
        # Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
        # grading period IDs. You will need to include these IDs in the request
        # body to make sure existing grading periods aren't deleted.
        body = {
          "gradingPeriods": [
            {
              # Specify the ID to make sure the grading period is not deleted.
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              # Specify the ID to make sure the grading period is not deleted.
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            },
            {
              # Does not include an ID because this grading period is an addition.
              "title": "Summer",
              "start_date": {
                "day": 1,
                "month": 6,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 8,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": False
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Suggerimenti utili sul campo booleano applyToExistingCoursework

È importante ricordare che il valore booleano applyToExistingCoursework è persistente , il che significa che se il valore booleano è stato impostato su True in una chiamata API precedente e non è stato modificato, gli aggiornamenti successivi ai periodi di valutazione verranno applicati ai lavori del corso esistenti.

Tieni presente che se modifichi questo valore booleano da True a False in una richiesta a UpdateGradingPeriodSettings, solo le nuove modifiche apportate a GradingPeriodSettings non verranno applicate ai lavori del corso esistenti. Le informazioni sui periodi di valutazione applicate ai lavori del corso nelle chiamate API precedenti quando il valore booleano era impostato su True non verranno rimosse. Un modo utile per pensare a questa impostazione booleana è che supporta l'associazione dei lavori del corso esistenti ai periodi di valutazione configurati, ma non supporta la rimozione delle associazioni esistenti tra i lavori del corso e i periodi di valutazione configurati.

Se elimini o modifichi il titolo di un periodo di valutazione, queste modifiche verranno propagate a tutti i lavori del corso esistenti, indipendentemente dall'impostazione del valore booleano applyToExistingCoursework.

Aggiornare un singolo periodo di valutazione nell'elenco

Per modificare alcuni dati associati a un periodo di valutazione esistente, includi l'ID del periodo di valutazione esistente nell'elenco con i dati modificati.

def update_existing_grading_period(classroom_service, course_id):
    """
    An existing grading period is updated.
    """
    try:
        # Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
        # grading period IDs. You will need to include these IDs in the request
        # body to make sure existing grading periods aren't deleted.
        body = {
          "gradingPeriods": [
            {
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            },
            {
              # The end date for this grading period will be modified from August 31, 2024 to September 10, 2024.
              # Include the grading period ID in the request along with the new data.
              "id": "SUMMER_GRADING_PERIOD_ID",
              "title": "Summer",
              "start_date": {
                "day": 1,
                "month": 6,
                "year": 2024
              },
              "end_date": {
                "day": 10,
                "month": 9,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": True
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Eliminare un singolo periodo di valutazione

Per eliminare un periodo di valutazione, ometti il periodo di valutazione dall'elenco. Tieni presente che se un periodo di valutazione viene eliminato, verrà eliminato anche qualsiasi riferimento al periodo di valutazione nei lavori del corso, indipendentemente dall'impostazione applyToExistingCoursework.

def delete_grading_period(classroom_service, course_id):
    """
    An existing grading period is deleted.
    """
    try:
        body = {
          "gradingPeriods": [
            {
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            }
          ]
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Gestire il campo gradingPeriodId in Lavori del corso

La risorsa Lavori del corso include un campo gradingPeriodId. Puoi utilizzare gli endpoint Lavori del corso per leggere e scrivere il periodo di valutazione associato a un lavoro del corso. Esistono tre modi per gestire questa associazione:

• Associazione automatica del periodo di valutazione in base alla data
• Periodo di valutazione associato personalizzato
• Nessuna associazione del periodo di valutazione

1. Associazione del periodo di valutazione in base alla data

Quando crei un lavoro del corso, puoi consentire a Classroom di gestire l'associazione del periodo di valutazione per te. Per farlo, ometti il campo gradingPeriodId dalla richiesta Lavori del corso. Poi, specifica i campi dueDate o scheduledTime nella richiesta Lavori del corso. Se dueDate rientra in un intervallo di date di un periodo di valutazione esistente, Classroom imposterà l'ID del periodo di valutazione nel lavoro del corso. Se il campo dueDate non è specificato, Classroom determinerà gradingPeriodId in base al campo scheduledTime. Se nessuno dei due campi è specificato o se non esiste una corrispondenza con l'intervallo di date del periodo di valutazione, non verrà impostato alcun gradingPeriodId nel lavoro del corso.

2. Periodo di valutazione associato personalizzato

Se vuoi associare il lavoro del corso a un periodo di valutazione diverso da quello che si allinea a dueDate o scheduledTime, puoi impostare manualmente il campo gradingPeriodId quando crei o aggiorni il lavoro del corso. Se imposti manualmente gradingPeriodId, Classroom non eseguirà l'associazione automatica del periodo di valutazione in base alla data.

3. Nessuna associazione del periodo di valutazione

Se non vuoi che il lavoro del corso sia associato a nessun periodo di valutazione in assoluto, imposta il campo gradingPeriodId nella richiesta Lavori del corso su una stringa vuota (gradingPeriodId: "").

Se utilizzi il linguaggio di programmazione Go e vuoi impostare nessun periodo di valutazione, devi includere anche il campo ForceSendFields nel corpo della richiesta. Con la libreria client Go, i valori predefiniti vengono omessi dalle richieste API a causa della presenza del tag del campo omitempty in tutti i campi. Il campo ForceSendFields ignora questo comportamento e invia la stringa vuota per indicare che non vuoi impostare alcun periodo di valutazione per quel lavoro del corso. Per ulteriori informazioni, consulta la documentazione della libreria client delle API di Google per Go.

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"GradingPeriodId"},
}

Che cosa succede all'ID del periodo di valutazione se la data di scadenza viene aggiornata?

Se stai aggiornando il campo dueDate di Lavori del corso e vuoi conservare un'associazione personalizzata o nessun periodo di valutazione, devi includere dueDate e gradingPeriodId in updateMask e nel corpo della richiesta. In questo modo, Classroom non sostituirà gradingPeriodId con il periodo di valutazione che corrisponde alla nuova dueDate.

body = {
  "dueDate": {
    "month": 6,
    "day": 10,
    "year": 2024
  },
  "dueTime": {
    "hours": 7
  },
  "gradingPeriodId": "<INSERT-GRADING-PERIOD-ID-OR-EMPTY-STRING>"
}
courseWork = classroom_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()