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 utilizzare l'API Classroom per impostare i periodi di valutazione su Coursework.

L'API Classroom offre due endpoint per leggere e scrivere informazioni sul periodo di valutazione in un corso:

  • GetGradingPeriodSettings: consente di leggere le impostazioni del periodo 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 applicandoli a tutti i compiti del corso esistenti.

Requisiti di idoneità e 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'endpointUpdateGradingPeriodSettings, 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 del dominio.

Impostare un ID periodo di valutazione su CourseWork

Gli insegnanti di un corso possono includere il gradingPeriodId durante la creazione o l'aggiornamento del compito utilizzando l'API, indipendentemente dalla licenza che gli è stata 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 questa opzione 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 riportate nella guida rapida di Python.
  • Sono stati aggiunti i seguenti ambiti alla schermata per il consenso OAuth del progetto:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • L'ID di un corso in cui devono essere modificati i periodi di valutazione. 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 i corsi, devi disporre delle credenziali di un insegnante. Gli amministratori non possono creare o modificare compiti 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.

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 sovrappongono a quelle di 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 permanente che ti consente di organizzare i corsi creati in precedenza in periodi di valutazione senza dover effettuare una chiamata API separata per modificare il valore gradingPeriodId per ogni corso. Se è impostato su True, Classroom imposta automaticamente gradingPeriodId su tutti i corsi 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 consegna nel corso, Classroom utilizzerà courseWork.scheduledTime. Se nessuno dei due campi è presente o se non esiste una corrispondenza tra le date di inizio e di fine di un periodo di valutazione esistente, il compito accademico non verrà associato a nessun periodo di valutazione.

Determinare se un utente può modificare le impostazioni del periodo 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 inviare richieste all'endpoint UpdateGradingPeriodSettings.

Python
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 del periodo di valutazione in un corso, puoi iniziare a inviare richieste all'endpoint UpdateGradingPeriodSettings. Eventuali modifiche alla risorsa GradingPeriodSettings vengono eseguite utilizzando l'endpoint UpdateGradingPeriodSettings, indipendentemente dal fatto 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 modifica il valore gradingPeriodId su qualsiasi attività didattica esistente compresa 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 dei singoli periodi di valutazione una volta che vengono restituiti nella risposta. Dovrai utilizzare questi ID per aggiornare i periodi di valutazione, se necessario.

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 del periodo 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.

Python
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 di un singolo periodo di valutazione devono essere eseguiti seguendo un pattern 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 l'elenco dei nuovi periodi di valutazione in una richiesta a UpdateGradingPeriodSettings.

Questo pattern ti aiuterà ad assicurarti che i titoli dei singoli 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 con dati modificati, sono considerati modifiche. Le proprietà non modificate rimangono invariate.
  4. I periodi di valutazione con ID nuovi o sconosciuti sono considerati errori.
Python

Il codice seguente si basa sull'esempio 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.

A tal fine, viene letto l'GradingPeriodSettings corrente, viene aggiunto un nuovo periodo di valutazione all'elenco e il valore booleano applyToExistingCoursework viene impostato su False. Tieni presente che i periodi di valutazione già applicati ai corsi esistenti non verranno rimossi. Nell'esempio precedente, i periodi di valutazione"Semestre 1 " e"Semestre 2" sono stati già applicati al Coursework esistente e non verranno rimossi da Coursework se applyToExistingCoursework è impostato su False nelle richieste successive.

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 dell'API precedente e non è stato modificato, gli aggiornamenti successivi ai periodi di valutazione verranno applicati al Corso esistente.

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 al Corso esistente. Eventuali informazioni sul periodo di valutazione applicate a Coursework nelle chiamate API precedenti quando il valore booleano era impostato su True non verranno rimosse. Un modo utile per considerare 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 periodi di valutazione configurati.

Se elimini o modifichi il titolo di un periodo di valutazione, le modifiche verranno propagate a tutti i corsi 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, la data di fine del periodo di valutazione "Estate" verrà modificata. Il campo applyToExistingCoursework verrà impostato su True. Tieni presente che se imposti questo valore booleano su True, verranno applicati tutti i periodi di valutazione configurati ai corsi esistenti. Nella richiesta API precedente, il valore booleano era impostato su False in modo che il periodo di valutazione "Estate" non venisse applicato al Corso esistente. Ora che questo campo booleano è impostato su True, il periodo di valutazione "Estate" verrà applicato a tutti i corsi esistenti corrispondenti.

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, 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 in questa guida, ometti il periodo di valutazione "Estate" per eliminarlo.

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 CourseWork

La risorsa Corso 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 alla data
  • periodo di valutazione personalizzato associato
  • nessuna associazione del periodo di valutazione

1. Associazione del periodo di valutazione in base alla data

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

2. Periodo di valutazione associato personalizzato

Se vuoi associare il Corso 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 del Corso. Se impostate manualmente gradingPeriodId, Classroom non eseguirà l'associazione automatica del periodo di valutazione in base alla data.

3. Nessuna associazione al periodo di valutazione

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

Se utilizzi il linguaggio di programmazione Go e vuoi impostare un periodo di valutazione vuoto, devi includere anche il campo ForceSendFields nel corpo della richiesta. Con la libreria client Go, i valori predefiniti vengono omessi dalle richieste all'API a causa della presenza del tag di campo omitempty in tutti i campi. Il campo ForceSendFields aggira questo problema e invia la stringa vuota per indicare che non vuoi che venga impostato alcun periodo di valutazione per il corso. Per saperne di più, consulta la documentazione della libreria client Go per le API di Google.

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

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

Se stai aggiornando il campo dueDate del corso e vuoi mantenere un'associazione personalizzata o senza periodo di valutazione, devi includere dueDate e gradingPeriodId in updateMask e nel corpo della richiesta. In questo modo, Classroom non sostituirà il 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_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()
Indietro
Impostare e aggiornare i voti
Avanti
Limitazioni