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:
- All'utente che effettua la richiesta è stata assegnata una licenza Google Workspace for Education Plus.
- Al proprietario del corso è assegnata una licenza Google Workspace for Education Plus.
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:
- Leggi l'elenco dei periodi di valutazione all'interno della risorsa
GradingPeriodSettings
utilizzando l'endpointGetGradingPeriodSettings
. - Apporta le modifiche scelte all'elenco dei periodi di valutazione.
- 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:
- I periodi di valutazione aggiunti all'elenco senza un ID sono considerati aggiuntivi.
- I periodi di valutazione mancanti nell'elenco sono considerati eliminazioni.
- I periodi di valutazione con un ID esistente, ma dati modificati sono considerati modifiche. Le proprietà non modificate vengono lasciate invariate.
- 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()