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 i compiti, i quiz e i 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 usare l'API Classroom per impostare i periodi di valutazione in CourseWork.

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

  • GetGradingPeriodSettings: consente di leggere le impostazioni del periodo di valutazione di 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 tutte le attività del corso esistenti.

Requisiti per le licenze

Modificare le impostazioni del periodo 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:

Leggere le impostazioni del periodo di valutazione in un corso

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

Impostare un ID periodo di valutazione su CourseWork

Gli insegnanti di un corso possono includere gradingPeriodId durante la creazione o l'aggiornamento 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 checkGradingPeriodsSetupEligibility sono consentite per conto di qualsiasi amministratore o insegnante. Usa questa metrica per determinare se l'utente può modificare i periodi di valutazione in un corso.

Prerequisiti

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

  • Un progetto Google Cloud. Puoi configurarne uno seguendo le istruzioni 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.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • L'ID di un corso in cui i periodi di valutazione devono essere modificati. 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. Per creare o modificare le attività del corso, ti servono le credenziali di un insegnante. Gli amministratori non possono creare o modificare CourseWork se non sono insegnanti del corso.

Gestisci la risorsa GradingPeriodSettings

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

L'elenco GradingPeriods rappresenta tutti i singoli periodi di valutazione in un corso. Devi specificare un titolo, una data di inizio e una data di fine per ogni singolo periodo di valutazione nell'elenco. Ogni periodo di valutazione di un corso deve avere un titolo univoco e le date di inizio e di fine dei diversi periodi di valutazione non possono sovrapporsi. Ogni periodo di valutazione avrà il proprio identificatore assegnato all'API Classroom.

Il valore booleano applyToExistingCoursework è un'impostazione persistente che consente di organizzare in periodi di valutazione di CourseWork creati in precedenza, senza dover effettuare una chiamata API separata per modificare gradingPeriodId per ogni CourseWork. Se viene impostato su True, Classroom imposterà automaticamente il gradingPeriodId su tutte le attività del corso esistenti se la courseWork.dueDate rientra nelle date di inizio e di fine di un periodo di valutazione esistente. Se non è stata impostata una data di consegna in CourseWork, Classroom utilizzerà courseWork.scheduledTime. Se nessuno dei campi è presente o se non esiste una corrispondenza tra le date di inizio e di fine di un periodo di valutazione esistente, CourseWork non sarà associato ad alcun periodo di valutazione.

Determinare se un utente può modificare le impostazioni del periodo di valutazione in un corso

Poiché la possibilità di creare e modificare i periodi di valutazione in Classroom è disponibile solo per gli utenti con una licenza specifica, l'API Classroom fornisce l'endpoint checkGradingPeriodsSetupEligibility per aiutarti a determinare in modo proattivo se un utente è in grado di effettuare richieste all'endpoint UpdateGradingPeriodSettings.

Python

def check_grading_period_setup_eligibility(classroom, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        grading_period_eligibility_response = classroom.courses().checkGradingPeriodsSetupEligibility(
          courseId=course_id, previewVersion="V1_20240401_PREVIEW").execute()

        # Retrieve the isGradingPeriodsSetupEligible boolean from the response.
        # If the boolean is `True`, the user is able to modify grading period settings in the course.
        is_grading_periods_eligible = grading_period_eligibility_response.get("isGradingPeriodsSetupEligible")
        return is_grading_periods_eligible
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Aggiungi periodi di valutazione

Ora che hai la certezza che l'utente disponga della licenza necessaria per modificare le impostazioni del periodo di valutazione di un corso, puoi iniziare a inviare richieste all'endpoint UpdateGradingPeriodSettings. Eventuali modifiche alla risorsa GradingPeriodSettings vengono eseguite utilizzando l'endpoint UpdateGradingPeriodSettings, che tu stia aggiungendo singoli periodi di valutazione, modificando periodi di valutazione esistenti o eliminando un periodo di valutazione.

Python

Nell'esempio seguente, la risorsa gradingPeriodSettings viene modificata per includere due periodi di valutazione. Il valore booleano applyToExistingCoursework è impostato su True, il che modificherà il valore gradingPeriodId in qualsiasi CourseWork esistente che rientra tra la data di inizio e la data di fine di un periodo di valutazione. Tieni presente che updateMask include entrambi i campi. Salva gli ID per i singoli periodi di valutazione una volta restituiti nella risposta. Dovrai utilizzare questi ID per aggiornare i periodi di valutazione, se necessario.

def create_grading_periods(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body,
          previewVersion="V1_20240401_PREVIEW"
        ).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

Leggi le impostazioni del periodo di valutazione

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

Python

def get_grading_period_settings(classroom, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom.courses().getGradingPeriodSettings(
          courseId=course_id, previewVersion="V1_20240401_PREVIEW").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 di un singolo periodo di valutazione devono essere eseguiti seguendo un modello di lettura, modifica e 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 modello ti aiuterà a garantire che i titoli dei singoli periodi di valutazione di un corso siano distinti e che non ci siano sovrapposizioni tra le date di inizio e di fine dei periodi di valutazione.

Tieni presente le seguenti regole relative all'aggiornamento dell'elenco dei periodi di valutazione:

  1. I periodi di valutazione aggiunti all'elenco senza un ID sono considerati aggiuntivi.
  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.

Python

Il seguente codice si basa sull'esempio contenuto in questa guida. Viene creato un nuovo periodo di valutazione con il titolo "Estate". Il valore booleano applyToExistingCoursework è impostato su False nel corpo della richiesta.

Per farlo, il valore GradingPeriodSettings corrente viene letto, viene aggiunto un nuovo periodo di valutazione all'elenco e il valore booleano applyToExistingCoursework è impostato su False. Tieni presente che eventuali periodi di valutazione già applicati a CourseWork esistenti non verranno rimossi. Nell'esempio precedente, i periodi di valutazione"Semestre 1 " e"Semestre 2" erano già stati applicati a CourseWork esistenti e non verranno rimossi da CourseWork se applyToExistingCoursework è impostato su False nelle richieste successive.

def add_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
          previewVersion="V1_20240401_PREVIEW").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 e significa che se il valore booleano era stato impostato su True in una precedente chiamata API e non è stato modificato, i successivi aggiornamenti ai periodi di valutazione verranno applicati alle attività del corso esistenti.

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

Se elimini o modifichi il titolo di un periodo di valutazione, le modifiche verranno propagate a tutti i CourseWork 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.

Python

In questo esempio, verrà modificata la data di fine del periodo di valutazione "Estate". Il campo applyToExistingCoursework verrà impostato su True. Tieni presente che l'impostazione di questo valore booleano su True applicherà tutti i periodi di valutazione configurati sulle attività del corso esistenti. Nella precedente richiesta API, il valore booleano era impostato su False in modo che il periodo di valutazione "Estate" non venisse applicato a CourseWork esistente. Ora che questo campo booleano è impostato su True, il periodo di valutazione "Estate" verrà applicato a tutti i CourseWork esistenti corrispondenti.

def update_existing_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
          previewVersion="V1_20240401_PREVIEW").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, omettilo dall'elenco. Tieni presente che se viene eliminato un periodo di valutazione, verrà eliminato anche qualsiasi riferimento al periodo di valutazione in CourseWork, indipendentemente dall'impostazione applyToExistingCoursework.

Python

Per continuare con l'esempio di questa guida, ometti il periodo di valutazione "Estate" per eliminarlo.

def delete_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods',
          previewVersion="V1_20240401_PREVIEW").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 CourseWork

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

  • associazione automatica del periodo di valutazione in base alle date
  • periodo di valutazione associato personalizzato
  • nessuna associazione al periodo di valutazione

1. Associazione del periodo di valutazione in base alle date

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

2. Periodo di valutazione associato personalizzato

Se vuoi associare un periodo di valutazione di CourseWork a un periodo di valutazione diverso da quello in linea con dueDate o scheduledTime, puoi impostare manualmente il campo gradingPeriodId durante la creazione o l'aggiornamento di CourseWork. Se imposti manualmente gradingPeriodId, Classroom non eseguirà l'associazione automatica del periodo di valutazione in base alle date.

3. Nessuna associazione al periodo di valutazione

Se non vuoi che il CourseWork venga associato ad alcun periodo di valutazione, imposta il campo gradingPeriodId nella richiesta di CourseWork su una stringa vuota (gradingPeriodId: "").

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

Se stai aggiornando il campo dueDate di CourseWork e vuoi mantenere un'associazione personalizzata o del periodo di valutazione, devi includere dueDate e gradingPeriodId nella maschera di aggiornamento e nel corpo della richiesta. In questo modo indichi a Classroom di non sostituire gradingPeriodId con il periodo di valutazione corrispondente al nuovo dueDate.

Python

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