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 CourseWork.
L'API Classroom offre due endpoint per leggere e scrivere informazioni sui periodi di valutazione in un corso:
GetGradingPeriodSettings: consente di leggere le impostazioni del periodo di valutazione in un corso.UpdateGradingPeriodSettings: consente di gestire le impostazioni del periodo di valutazione in un corso aggiungendo, modificando ed eliminando i periodi di valutazione e applicando i periodi di valutazione configurati a tutti i compiti esistenti.
Requisiti di idoneità e licenza
Modificare le impostazioni del periodo di valutazione in un corso
Per creare, modificare o eliminare 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.
- L'utente che effettua la richiesta ha una licenza Google Workspace for Education Plus assegnata.
- Il proprietario del corso ha una licenza Google Workspace for Education Plus assegnata.
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 assegnata. Ciò significa che le richieste
all'endpoint GetGradingPeriodSettings sono consentite per conto di qualsiasi amministratore
di dominio o insegnante.
Imposta un ID periodo di valutazione su CourseWork
Gli insegnanti di un corso possono includere gradingPeriodId durante la creazione o l'aggiornamento
di CourseWork utilizzando l'API, indipendentemente dalla licenza assegnata.
Controllare 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 impostazione 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.courseshttps://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 compiti, devi disporre delle credenziali di un insegnante. Gli amministratori non possono creare o modificare i compiti se non sono insegnanti del corso.
Gestire la risorsa GradingPeriodSettings
La risorsa GradingPeriodSettings include un elenco di singoli
GradingPeriods e un campo booleano chiamato applyToExistingCoursework.
Assicurati che ogni 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:le date di inizio e di fine di ogni periodo di valutazione non devono sovrapporsi 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 persistente che ti consente di organizzare i compiti creati in precedenza in periodi di valutazione senza dover effettuare una chiamata API separata per modificare gradingPeriodId per ogni compito. Se
è impostato su True, Classroom imposterà automaticamente
il gradingPeriodId su tutti i compiti esistenti se il
courseWork.dueDate rientra nelle date di inizio e
fine di un periodo di valutazione esistente. Se non è stata impostata alcuna data di scadenza per il compito, Classroom
utilizzerà il courseWork.scheduledTime. Se nessuno dei due campi è presente o
non esiste alcuna corrispondenza tra le date di inizio e fine di un periodo di valutazione esistente, il
compito non verrà associato ad alcun 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 effettuare 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. Qualsiasi modifica alla risorsa
GradingPeriodSettings viene eseguita 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
Nel seguente esempio, la risorsa gradingPeriodSettings viene modificata
per includere due periodi di valutazione. Il valore booleano applyToExistingCoursework è
impostato su True, che modificherà gradingPeriodId in qualsiasi
CourseWork esistente compreso tra la data di inizio e 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 restituiti nella risposta. Se necessario, dovrai utilizzare
questi ID per aggiornare i periodi 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
Read grading period settings
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_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 e scrittura. Ciò significa che dovresti:
- Leggi l'elenco dei periodi di valutazione all'interno della risorsa
GradingPeriodSettingsutilizzando l'endpointGetGradingPeriodSettings. - Apporta le modifiche scelte all'elenco dei periodi di valutazione.
- Invia l'elenco dei nuovi periodi di valutazione in una richiesta a
UpdateGradingPeriodSettings.
Questo pattern ti aiuterà a garantire che i singoli titoli dei periodi di valutazione di un corso siano distinti e che non vi sia sovrapposizione 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 aggiunte.
- I periodi di valutazione mancanti nell'elenco vengono considerati eliminazioni.
- I periodi di valutazione con un ID esistente, ma con 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 codice seguente si basa sull'esempio riportato 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 questo scopo, viene letto l'attuale GradingPeriodSettings, 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 compiti esistenti non verranno rimossi. Nell'esempio precedente,
i periodi di valutazione"Semestre 1 " e"Semestre 2" sono già stati applicati
ai compiti esistenti e non verranno rimossi 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 viene
memorizzato, 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 compiti esistenti.
Tieni presente che se modifichi questo valore booleano da True a False in una richiesta
a UpdateGradingPeriodSettings, solo le nuove modifiche che apporti a
GradingPeriodSettings non verranno applicate ai compiti esistenti. Le 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 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 periodi di valutazione configurati.
Se elimini o modifichi il titolo di un periodo di valutazione, queste modifiche verranno
propagate a tutti i compiti 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. Nota: se imposti questo valore booleano su True, tutti i periodi di valutazione configurati verranno applicati ai compiti esistenti. Nella richiesta API precedente, il valore booleano era
impostato su False in modo che il periodo di valutazione "Estate" non venisse applicato
ai compiti esistenti. Ora che questo campo booleano è impostato su True, il
periodo di valutazione "Estate" verrà applicato a tutti i compiti esistenti che
corrispondono.
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
un periodo di valutazione viene eliminato, qualsiasi riferimento al periodo di valutazione in
CourseWork verrà eliminato indipendentemente dall'impostazione applyToExistingCoursework.
Python
Per continuare 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 Attività del corso
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 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 CourseWork, 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 CourseWork. Se dueDate rientra in un intervallo di date del periodo di valutazione esistente, Classroom imposterà l'ID del periodo di valutazione in CourseWork. Se il campo dueDate non è specificato,
Classroom determinerà il gradingPeriodId in base al
campo scheduledTime. Se non viene specificato alcun campo o se non esiste una corrispondenza con l'intervallo di date del periodo di valutazione, non verrà impostato alcun gradingPeriodId nel compito.
2. Periodo di valutazione associato personalizzato
Se vuoi associare il compito a un periodo di valutazione diverso
da quello allineato a dueDate o scheduledTime, puoi impostare manualmente
il campo gradingPeriodId quando crei o aggiorni il compito. Se imposti
manualmente il 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 compito sia associato ad alcun periodo di valutazione, imposta il campo gradingPeriodId nella richiesta di compito 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 di campo omitempty in tutti i campi.
Il campo ForceSendFields lo aggira e invia la stringa vuota per indicare
che non vuoi impostare alcun periodo di valutazione per il compito. Per saperne di più, consulta la
documentazione della libreria client Go delle API di Google.
Vai
courseWork := &classroom.CourseWork{
Title: "Homework questions",
WorkType: "ASSIGNMENT",
State: "DRAFT",
// ...other CourseWork fields...
GradingPeriodId: "",
ForceSendFields: []string{"GradingPeriodId"},
}
Cosa succede all'ID periodo di valutazione se la data di scadenza viene aggiornata?
Se stai aggiornando il campo dueDate di CourseWork e vuoi conservare 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 eseguirà l'override del gradingPeriodId con il periodo di valutazione che corrisponde 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()