Interagire con gli allegati

Questa pagina illustra i dettagli di implementazione per la creazione di un allegato e per lavorare con i contenuti inviati 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 dell'insegnante dell'allegato.
  • studentViewUri: l'URI per la visualizzazione dello studente dell'allegato.
  • studentWorkReviewUri: l'URI che consente all'insegnante di 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 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.

Dettagli relativi ai contenuti inviati dagli studenti

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. submissionId e attachmentId vengono archiviati 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 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 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 i lavori degli studenti. Utilizza l'endpoint courses.courseWork.addOnAttachments.studentSubmissions per recuperare o modificare le informazioni su un compito inviato da uno studente.

Rileva lo stato di invio

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

  • NEW, se lo studente non ha mai effettuato l'accesso al compito.
  • CREATED, se lo studente ha creato un compito, ma non lo ha ancora inviato.
  • TURNED_IN, se lo studente ha inviato il lavoro all'insegnante.
  • RETURNED, se l'insegnante ha restituito il compito 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. Potresti quindi modificare le visualizzazioni o le opzioni fornite allo studente in base allo stato restituito. Potrebbero essere incluse funzionalità come:

  • Visualizza lo stato di consegna dei compiti all'interno del tuo componente aggiuntivo. In questo modo, gli studenti possono evitare potenziali confusioni e assicurarsi di non dimenticare di consegnare un compito.
  • Limitare i privilegi di modifica dei contenuti inviati. Se il compito ha lo stato CREATED o RECLAIMED_BY_STUDENT, lo studente potrebbe avere l'autorizzazione per modificare quanto inviato. Se il compito ha lo stato TURNED_IN o RETURNED, lo studente potrebbe non essere autorizzato a modificare i contenuti inviati.

Voti e più allegati

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

Impostare il voto di un compito

Puoi modificare un compito inviato dallo 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 compito. 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 maggiori dettagli 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 le seguenti condizioni sono vere:

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

Tieni inoltre presente 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 un voto viene restituito a Google Classroom. La distinta fondamentale è se scegli di memorizzare le credenziali dell'insegnante, poiché solo l'insegnante può modificare un voto.

Esistono due momenti di aggiunta in cui puoi trasmettere un voto a Google Classroom: quando lo studente completa il proprio lavoro o quando l'insegnante lo apre nell'iframe di 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 continui dei voti. Gli insegnanti non devono fare nulla in particolare per inserire i voti 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 del livello di comprensione degli studenti senza aprire ogni invio.

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 proprio lavoro. Una volta inviato, imposta il voto utilizzando le credenziali memorizzate.

Se non vuoi caricare le credenziali dell'insegnante durante una sessione dello studente, puoi utilizzare le credenziali dell'insegnante attivo quando carica il lavoro dello studente nell'iframe di Revisione del lavoro dello studente. Tuttavia, questa operazione potrebbe non offrire un'esperienza utente particolarmente fluida, in quanto i voti nell'interfaccia utente di Classroom non si aggiornano in tempo reale e gli insegnanti dovranno aprire l'iframe di Revisione dei lavori degli studenti di ogni compito inviato.

Rilevare le modifiche ai voti dei compiti

Gli insegnanti possono modificare le impostazioni dei voti in Classroom dopo aver creato un compito. Queste modifiche possono includere:

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

Per visualizzare le impostazioni di valutazione correnti di un compito, ti consigliamo di inviare una richiesta GET all'endpoint courses.courseWork. La risposta include il valore maxPoints corrente. Un compito non valutato 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 di un allegato del componente aggiuntivo. Il valore del voto viene impostato utilizzando il pointsEarned campo. Valuta la possibilità di controllare e, se necessario, aggiornare questo valore se il tuo prodotto consente agli insegnanti di modificare il voto di uno studente per una determinata attività.