Interagire con gli allegati

Questa pagina illustra i dettagli dell'implementazione per creare un allegato e lavorare con i contenuti inviati dagli studenti. Tieni presente che potrebbe essere necessario fornire parametri correlati agli allegati quando effettui queste richieste.

Crea un allegato

Crea un allegato inviando una richiesta CREATE all'endpoint courses.*.addOnAttachments.create appropriato. La richiesta deve includere un'istanza di AddOnAttachment nel corpo della richiesta.

I seguenti campi sono obbligatori durante la creazione di un allegato:

  • title: il nome della stringa dell'allegato.
  • teacherViewUri: l'URI della visualizzazione per gli insegnanti dell'allegato.
  • studentViewUri: l'URI della visualizzazione studente dell'allegato.
  • studentWorkReviewUri: l'URI dell'insegnante per vedere il lavoro dello studente sull'allegato. Questo campo è obbligatorio solo per gli allegati di tipo attività.

Ti consigliamo di includere alcuni dei seguenti campi facoltativi:

  • dueDate e dueTime se specifichi la data di scadenza dell'allegato.
  • maxPoints: il voto massimo per l'allegato. Deve essere un valore diverso da zero se vuoi supportare il pass-back dei voti. Si applica solo agli allegati di tipo attività.

Per ulteriori dettagli su questi campi, consulta la guida di riferimento della risorsa AddOnAttachment.

Dettagli dell'invio dello studente

Un tipico flusso di lavoro di invio segue questi passaggi:

  1. Uno studente avvia studentViewUri per completare un'attività.
  2. Il componente aggiuntivo recupera un submissionId dal metodo getAddOnContext utilizzando le credenziali dello studente.
  3. I valori submissionId e attachmentId vengono memorizzati dallo sviluppatore del componente aggiuntivo come identificatore univoco del lavoro dello studente. Nel caso in cui un insegnante copi un compito in Classroom, puoi utilizzare la chiave composita di questi due parametri per visualizzare un nuovo allegato nel compito copiato. Per ulteriori dettagli, consulta la nostra pagina sui contenuti copiati.
  4. Un insegnante interessato a rivedere i lavori degli studenti avvia studentWorkReviewUri. La richiesta include i seguenti parametri di query: courseId, itemId, itemType, attachmentId e submissionId.
  5. Lo sviluppatore del componente aggiuntivo utilizza questi quattro ID per recuperare il lavoro dello studente. Utilizza l'endpoint courses.courseWork.addOnAttachments.studentSubmissions per recuperare o modificare le informazioni relative ai contenuti inviati da uno studente.

Rileva stato di invio

Invia una richiesta GET all'endpoint courses.courseWork.addOnAttachments.studentSubmissions per ottenere i dettagli su uno specifico submissionId. Ricevi un oggetto AddOnAttachmentStudentSubmission, che contiene il voto (pointsEarned) e lo stato attuale (postSubmissionState) dell'invio. Lo stato di invio può essere uno dei seguenti valori:

  • NEW, se lo studente non ha mai eseguito l'accesso ai contenuti inviati.
  • CREATED, se lo studente ha creato un invio ma non li ha ancora inviati.
  • TURNED_IN, se lo studente ha inviato il suo lavoro all'insegnante.
  • RETURNED, se l'insegnante ha restituito i contenuti inviati allo studente.
  • RECLAIMED_BY_STUDENT, se lo studente ha annullato l'invio del proprio lavoro.

Utilizza questo endpoint per rilevare lo stato del lavoro dello studente nel tuo componente aggiuntivo. Puoi quindi modificare le visualizzazioni o le opzioni fornite allo studente in base allo stato restituito. Potrebbero essere incluse funzionalità quali:

  • Visualizzazione dello stato di consegna dei compiti all'interno del componente aggiuntivo. In questo modo, gli studenti possono evitare ogni possibile confusione e assicurarsi di non fallire per errore a consegnare un compito.
  • Limitazione dei privilegi di modifica per l'invio. Se lo stato del compito è CREATED o RECLAIMED_BY_STUDENT, lo studente potrebbe essere autorizzato a modificare i contenuti inviati. Se lo stato del compito è TURNED_IN o RETURNED, lo studente potrebbe non essere autorizzato a modificare i contenuti inviati.

Voti e più allegati

È possibile utilizzare un solo allegato di un componente aggiuntivo per impostare il voto per un singolo compito. Se un insegnante crea più allegati di tipo attività che forniscono un valore maxPoints, solo il primo di questo allegato può impostare il voto del compito. Lascia il valore maxPoints non impostato o impostalo su zero per disabilitare il pass-back dei voti per un allegato.

Impostare il voto di un invio

Puoi modificare i contenuti inviati da uno studente inviando una richiesta PATCH all'endpoint courses.courseWork.addOnAttachments.studentSubmissions. Il corpo della richiesta deve includere un'istanza di AddOnAttachmentStudentSubmission con i valori modificati. Imposta il campo pointsEarned per modificare il voto di un invio. Il valore trasmesso in pointsEarned diventa un voto provvisorio visibile all'insegnante nella UI di Classroom. L'insegnante può modificare il voto provvisorio prima di restituire il compito agli studenti. Consulta la Panoramica della valutazione nell'interfaccia utente di Classroom per i dettagli su come vengono presentati i voti agli insegnanti.

Tieni presente che puoi impostare il voto con pointsEarned solo se le seguenti condizioni sono vere:

  • L'allegato deve avere un valore maxPoints positivo.
  • Il componente aggiuntivo deve essere l'autore originale dell'allegato.

Tieni inoltre presente che puoi modificare il valore maxPoints di AddOnAttachment già creato inviando una richiesta PATCH all'endpoint addOnAttachments.

Quando impostare un voto

Hai la possibilità di scegliere quando restituire un voto a Google Classroom. La differenza fondamentale è se scegli di archiviare le credenziali dell'insegnante, poiché solo l'insegnante può modificare un voto.

Puoi passare un voto a Google Classroom in due momenti aggiuntivi: quando lo studente completa il lavoro o quando l'insegnante apre il lavoro nell'iframe della revisione del lavoro dello studente.

Se vuoi impostare i voti quando lo studente completa il lavoro, devi archiviare le credenziali offline di un insegnante, quindi recuperarle e utilizzarle per modificare il voto quando lo studente completa il lavoro. Questo metodo offre alcuni potenziali vantaggi:

  • Fornire aggiornamenti dei voti senza interruzioni. Gli insegnanti non devono eseguire alcuna azione speciale per inserire i voti nell'UI di Classroom.
  • Fornire informazioni in tempo reale sull'avanzamento di un corso attraverso un compito. Impostando i voti man mano che gli studenti completano gli allegati, gli insegnanti possono avere un'idea della loro comprensione senza dover aprire ogni singolo compito.

Tieni presente che questo approccio consente anche l'utilizzo di un approccio asincrono per la sincronizzazione dei voti. Potresti chiedere periodicamente all'endpoint AddOnAttachmentStudentSubmission di rilevare quando uno studente ha inviato il proprio lavoro. Una volta inviato, imposta il voto utilizzando le credenziali archiviate.

Se non vuoi caricare le credenziali dell'insegnante durante una sessione studente, puoi utilizzare le credenziali dell'insegnante attivo quando carica i contenuti inviati dallo studente nell'iframe della revisione del lavoro dello studente. Tuttavia, ciò potrebbe non garantire un'esperienza utente particolarmente fluida, poiché i voti nella UI di Classroom non vengono aggiornati in tempo reale e gli insegnanti dovrebbero aprire l'iframe della revisione del lavoro dello studente di ogni compito.

Rileva le modifiche nei voti dei compiti

gli insegnanti possono modificare le impostazioni dei voti in Classroom dopo aver creato un compito. Tali modifiche potrebbero includere:

  • Modifica del valore dei punti assegnati.
  • Modifica del valore maxPoints di un compito.
  • Modifica dell'eventuale voto del compito.

Per visualizzare le attuali impostazioni di valutazione di un compito, ti consigliamo di inviare una richiesta GET all'endpoint courses.courseWork. La risposta include il valore maxPoints corrente. Un compito senza voto ha un valore maxPoints nullo o pari a zero.

Se hai restituito un voto a Classroom, utilizza l'endpoint courses.courseWork.addOnAttachments.studentSubmissions per recuperare o modificare il voto per un allegato aggiuntivo. Il valore del voto viene impostato utilizzando il campo pointsEarned. Controlla e, se necessario, aggiorna questo valore se il tuo prodotto consente agli insegnanti di modificare il punteggio di uno studente per una determinata attività.