Interagire con gli allegati

Questa pagina illustra i dettagli di implementazione per la creazione di un allegato, le azioni consigliate quando gli utenti aprono gli allegati e l'utilizzo dei compiti consegnati dagli studenti. Tieni presente che potresti dover fornire parametri relativi agli allegati quando effettui queste richieste.

Creare 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 quando crei un allegato:

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

Potresti voler 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 trasferimento dei voti. Si applica solo agli allegati di tipo attività.

Per ulteriori dettagli su questi campi, consulta il riferimento alla risorsa AddOnAttachment.

Convalidare le credenziali e il ruolo dell'utente

L'iframe della visualizzazione studente, l'iframe della revisione del lavoro dello studente e l'iframe della visualizzazione insegnante sono tutti progettati per presentare i contenuti all'utente anziché modificare un compito di Classroom. Quando apri una di queste visualizzazioni, valuta la possibilità di eseguire le seguenti operazioni:

  • Ottieni le credenziali OAuth per l'utente.
  • Invia una richiesta courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext o announcements.getAddOnContext in base a itemType per convalidare il ruolo dell'utente.
  • Esamina la risposta per verificare se sono presenti TeacherContext o StudentContext. Può essere restituito solo uno dei due, a seconda del ruolo dell'utente nel corso.
  • Se l'utente attuale è uno studente e itemType è courseWork, registra submissionId dalla risposta con il lavoro dello studente. I valori submissionIds corrispondono agli iframe dei componenti aggiuntivi e sono necessari per il trasferimento dei voti e per mostrare il lavoro degli studenti agli insegnanti nello strumento di valutazione.
  • Se attachmentId è già noto al componente aggiuntivo, mostra l'interfaccia utente dell'allegato appropriata.
  • In caso contrario, questo allegato deve essere stato copiato da un altro elemento dello stream o corso. Per consigli su questo scenario, consulta la guida Gestire i contenuti copiati per raccomandazioni.

Dettagli dei compiti consegnati dagli studenti

Un flusso di lavoro tipico per i compiti consegnati 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. Lo sviluppatore del componente aggiuntivo memorizza submissionId e attachmentId come identificatore univoco del lavoro dello studente. Se un insegnante copia un compito in Classroom, puoi utilizzare la chiave composta 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 il lavoro dello studente 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 su un compito consegnato da uno studente.

Rilevare lo stato del compito consegnato

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

  • NEW, se lo studente non ha mai eseguito l'accesso al compito consegnato.
  • CREATED, se lo studente ha creato un compito consegnato ma non l'ha ancora inviato.
  • TURNED_IN, se lo studente ha inviato il suo lavoro all'insegnante.
  • RETURNED, se l'insegnante ha restituito il compito consegnato allo studente.
  • RECLAIMED_BY_STUDENT, se lo studente ha "annullato l'invio" del suo lavoro.

Utilizza questo endpoint per rilevare lo stato del lavoro dello studente nel tuo componente aggiuntivo. A seconda dello stato restituito, potresti modificare le visualizzazioni o le opzioni fornite allo studente. Potrebbero essere incluse funzionalità quali:

  • Visualizzare lo stato di consegna dei compiti all'interno del componente aggiuntivo. In questo modo, gli studenti possono evitare potenziali confusione e assicurarsi di non dimenticare di consegnare un compito.
  • Limitare i privilegi di modifica dei compiti consegnati. Se il compito ha lo stato CREATED o RECLAIMED_BY_STUDENT, lo studente potrebbe essere autorizzato a modificare il compito consegnato. Se il compito ha lo stato TURNED_IN o RETURNED, lo studente potrebbe non essere autorizzato a modificare il compito consegnato.

Voti e più allegati

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

Impostare il voto di un compito consegnato

Puoi modificare un compito consegnato da uno studente inviando una PATCH richiesta all'courses.courseWork.addOnAttachments.studentSubmissions endpoint. Il corpo della richiesta deve includere un'istanza di AddOnAttachmentStudentSubmission con i valori modificati. Imposta il campo pointsEarned per modificare il voto di un compito consegnato. Il valore passato in pointsEarned diventa un voto provvisorio visibile all'insegnante nell'interfaccia utente di Classroom. Gli insegnanti possono modificare il voto provvisorio prima di restituire il compito agli studenti. Per informazioni dettagliate su come vengono presentati i voti agli insegnanti, consulta la panoramica della valutazione nell' interfaccia utente di Classroom.

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

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

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

Quando impostare un voto

Puoi scegliere quando trasferire un voto a Google Classroom. La distinzione fondamentale è se scegli di archiviare le credenziali dell'insegnante, poiché solo l'insegnante può modificare un voto.

Esistono due momenti del componente aggiuntivo in cui potresti trasferire un voto a Google Classroom: quando lo studente completa il suo lavoro o quando l'insegnante apre il lavoro dello studente 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 fare in modo che i voti vengano inseriti nell'interfaccia utente di Classroom.
  • Fornire informazioni in tempo reale sull'avanzamento di un corso in un compito. Impostando i voti man mano che gli studenti completano gli allegati, gli insegnanti possono farsi un'idea della comprensione degli studenti senza aprire ogni compito consegnato.

Tieni presente che questo approccio consente anche un approccio asincrono alla sincronizzazione dei voti. Potresti eseguire periodicamente il polling dell'endpoint AddOnAttachmentStudentSubmission per rilevare quando uno studente ha inviato il suo lavoro. Una volta inviato, imposta il voto del compito consegnato utilizzando le credenziali archiviate.

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

Rilevare le modifiche ai voti dei compiti

Gli insegnanti possono modificare le impostazioni dei voti in Classroom dopo la creazione di un compito. Queste modifiche potrebbero includere:

  • Modificare il valore in punti assegnato.
  • Modificare il valore maxPoints di un compito.
  • Modificare se il compito deve essere valutato.

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

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