Cómo interactuar con archivos adjuntos

En esta página, se describen los detalles de implementación para crear un archivo adjunto, las acciones recomendadas cuando los usuarios abren archivos adjuntos y el trabajo con las entregas de los estudiantes. Ten en cuenta que es posible que debas proporcionar parámetros relacionados con los archivos adjuntos cuando realices estas solicitudes.

Crea un adjunto

Crea un adjunto con una solicitud CREATE al extremo courses.*.addOnAttachments.create correspondiente. Tu solicitud debe incluir una instancia de AddOnAttachment en el cuerpo.

Los siguientes campos son obligatorios cuando se crea un adjunto:

  • title: Es el nombre de cadena del adjunto.
  • teacherViewUri: Es el URI de la vista para el profesor del adjunto.
  • studentViewUri: Es el URI de la vista del estudiante del adjunto.
  • studentWorkReviewUri: Es el URI para que el profesor vea el trabajo del estudiante en el archivo adjunto. Este campo solo es obligatorio para los archivos adjuntos de tipo actividad.

Puedes incluir algunos de los siguientes campos opcionales:

  • dueDate y dueTime si especificas cuándo vence el adjunto
  • maxPoints: Es la calificación máxima del adjunto. Debe ser un valor distinto de cero si deseas admitir la devolución de calificaciones. Se aplica solo a los archivos adjuntos de tipo de actividad.

Consulta la referencia del recurso AddOnAttachment para obtener más detalles sobre estos campos.

Valida las credenciales y el rol del usuario

Los iframes de Vista del estudiante, iframe de Revisión del trabajo del estudiante y iframe de Vista del profesor están diseñados para presentar contenido al usuario en lugar de modificar una tarea de Classroom. Considera hacer lo siguiente cuando se abra una de estas vistas:

  • Obtén credenciales de OAuth para el usuario.
  • Realiza una solicitud de courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext o announcements.getAddOnContext según el itemType para validar el rol del usuario.
  • Inspecciona la respuesta para ver si están presentes TeacherContext o StudentContext. Solo se puede devolver uno, que corresponde al rol del usuario en el curso.
  • Si el usuario actual es estudiante y el itemType es courseWork, registra el submissionId de la respuesta con el trabajo del estudiante. La coincidencia de submissionIds en los elementos iframe del complemento, y son necesarios para devolver las calificaciones y mostrar el trabajo de los estudiantes a los profesores en la herramienta de calificación.
  • Si el complemento ya conoce el attachmentId, muestra la IU de adjuntos adecuada.
  • De lo contrario, este adjunto debe haberse copiado de otro elemento de transmisión o curso. Consulta la guía Cómo controlar el contenido copiado para obtener recomendaciones sobre esta situación.

Detalles de la entrega del estudiante

Un flujo de trabajo de envío típico sigue estos pasos:

  1. Un estudiante inicia studentViewUri para completar una actividad.
  2. El complemento recupera un submissionId del método getAddOnContext con las credenciales del estudiante.
  3. El desarrollador del complemento almacena submissionId y attachmentId como identificadores únicos del trabajo del estudiante. En el caso de que un profesor copie una tarea en Classroom, puedes usar la clave compuesta de estos dos parámetros para mostrar un nuevo adjunto en la tarea copiada. Consulta nuestra página sobre el contenido copiado para obtener más detalles.
  4. Un profesor interesado en revisar el trabajo de los estudiantes inicia la studentWorkReviewUri. La solicitud incluye los siguientes parámetros de búsqueda: courseId, itemId, itemType, attachmentId y submissionId.
  5. El desarrollador del complemento usa estos cuatro IDs para recuperar el trabajo del estudiante. Usa el extremo courses.courseWork.addOnAttachments.studentSubmissions para recuperar o modificar información sobre la entrega de un estudiante.

Detecta el estado del envío

Envía una solicitud GET al extremo courses.courseWork.addOnAttachments.studentSubmissions para obtener detalles sobre un submissionId específico. Recibirás un objeto AddOnAttachmentStudentSubmission, que contiene la calificación de la entrega (pointsEarned) y el estado actual (postSubmissionState). El estado de la entrega puede ser uno de los siguientes valores:

  • NEW, si el estudiante nunca accedió a la entrega.
  • CREATED, si el estudiante creó un envío, pero aún no lo envió.
  • TURNED_IN, si el estudiante envió su trabajo al profesor
  • RETURNED, si el profesor devolvió la tarea al estudiante.
  • RECLAIMED_BY_STUDENT, si el estudiante "no envió" su trabajo

Usa este extremo para detectar el estado del trabajo del estudiante en tu complemento. Luego, puedes ajustar las vistas o las opciones que se le proporcionan al estudiante según el estado que se devolvió. Esto puede incluir funciones como las siguientes:

  • Mostrar el estado de entrega de las tareas en tu complemento Esto puede ayudar a los estudiantes a evitar posibles confusiones y garantizar que no dejen de entregar una tarea por error.
  • Restringe los privilegios de edición de envíos. Si la tarea tiene el estado CREATED o RECLAIMED_BY_STUDENT, es posible que se le permita al estudiante editar su entrega. Si la tarea tiene el estado TURNED_IN o RETURNED, es posible que el estudiante no pueda editar su entrega.

Calificaciones y varios archivos adjuntos

Solo se puede usar un archivo adjunto de complemento para establecer la calificación de una sola tarea. Si un profesor crea más de un adjunto de tipo de actividad que proporciona un valor de maxPoints, solo el primer adjunto de este tipo puede establecer la calificación de la tarea. Deja el valor maxPoints sin configurar o establécelo en cero para inhabilitar la devolución de calificaciones de un archivo adjunto.

Cómo establecer la calificación de un envío

Para modificar la entrega de un estudiante, envía una solicitud PATCH al extremo courses.courseWork.addOnAttachments.studentSubmissions. El cuerpo de la solicitud debe incluir una instancia de AddOnAttachmentStudentSubmission con los valores modificados. Establece el campo pointsEarned para modificar la calificación de un envío. El valor que se pasa en pointsEarned se convierte en una calificación preliminar que el profesor puede ver en la IU de Classroom. Los profesores pueden modificar la calificación preliminar antes de devolver la tarea a los estudiantes. Consulta Descripción general de la calificación en la IU de Classroom para obtener detalles sobre cómo se presentan las calificaciones a los profesores.

Ten en cuenta que solo puedes establecer la calificación con pointsEarned si se cumplen las siguientes condiciones:

  • El adjunto debe tener un valor de maxPoints positivo.
  • El complemento debe haber sido el creador original del archivo adjunto.

Ten en cuenta también que puedes modificar el valor maxPoints de un AddOnAttachment ya creado si envías una solicitud PATCH al endpoint addOnAttachments.

Cuándo establecer una calificación

Tienes algunas opciones para elegir cuándo se devuelven las calificaciones a Google Classroom. La distinción fundamental es si eliges almacenar las credenciales del profesor, ya que solo él puede modificar una calificación.

Hay dos momentos en los que puedes pasar una calificación a Google Classroom: cuando el estudiante completa su trabajo o cuando el profesor abre el trabajo del estudiante en el iframe de Revisión del trabajo del estudiante.

Si deseas establecer calificaciones cuando el estudiante complete el trabajo, debes almacenar las credenciales sin conexión del profesor y, luego, recuperarlas y usarlas para modificar la calificación cuando el estudiante complete el trabajo. Este método proporciona algunos beneficios potenciales:

  • Proporcionar actualizaciones de calificaciones fluidas Los profesores no necesitan realizar ninguna acción especial para que las calificaciones se muestren en la IU de Classroom.
  • Proporcionar estadísticas en tiempo real sobre el progreso de una clase en una tarea Al establecer calificaciones a medida que los estudiantes completan los archivos adjuntos, los profesores pueden tener una idea de la comprensión de sus estudiantes sin abrir cada envío.

Ten en cuenta que este enfoque también permite un enfoque asíncrono para la sincronización de calificaciones. Es posible que sondee periódicamente el extremo AddOnAttachmentStudentSubmission para detectar cuándo un estudiante envió su trabajo. Cuando se haya enviado, establece la calificación del envío con las credenciales almacenadas.

Si no quieres cargar las credenciales del profesor durante una sesión del estudiante, puedes usar las credenciales del profesor activo cuando cargue el envío del estudiante en el iframe de revisión del trabajo del estudiante. Sin embargo, es posible que esto no proporcione una experiencia del usuario especialmente fluida, ya que las calificaciones en la IU de Classroom no se actualizan en tiempo real y los profesores deberían abrir el iframe de revisión del trabajo del estudiante de cada envío.

Detecta cambios en las calificaciones de las tareas

Los profesores pueden editar la configuración de calificaciones en Classroom después de crear una tarea. Estas ediciones pueden incluir lo siguiente:

  • Cambiar el valor de los puntos asignados
  • Cambia el valor de maxPoints de una asignación.
  • Cambiar si la tarea debe calificarse.

Para ver la configuración actual de calificación de una tarea, te recomendamos que envíes una solicitud GET al extremo courses.courseWork. La respuesta incluye el valor maxPoints actual. Una tarea sin calificar tiene un valor maxPoints nulo o cero.

Si ya devolviste una calificación a Classroom, usa el extremo courses.courseWork.addOnAttachments.studentSubmissions para recuperar o modificar la calificación de un adjunto del complemento. El valor de la calificación se establece con el campo pointsEarned. Considera verificar y, si es necesario, actualizar este valor si tu producto permite que los profesores editen la puntuación de un estudiante para una actividad en particular.