Cómo interactuar con archivos adjuntos

En esta página, se analizan los detalles de implementación para crear un archivo adjunto y trabajar 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 mediante la emisión de una solicitud CREATE al extremo courses.*.addOnAttachments.create adecuado. Tu solicitud debe incluir una instancia de AddOnAttachment en el cuerpo de la solicitud.

Los siguientes campos son obligatorios cuando se crea un adjunto:

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

Te recomendamos incluir algunos de los siguientes campos opcionales:

• dueDate y dueTime si especifican la fecha de vencimiento del adjunto.
• maxPoints: Es la calificación máxima del archivo adjunto. Debe ser un valor distinto de cero si quieres admitir la devolución de calificaciones. Solo se aplica a los adjuntos de tipo de actividad.

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

Detalles de entrega del estudiante

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

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

Importante: Cuando emitas solicitudes PATCH, no olvides proporcionar también el updateMask. El valor updateMask debe ser una lista separada por comas de los nombres de campo que se modificarán.

Detecta el estado de envío

Emite 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 del envío puede ser uno de los siguientes valores:

• NEW, si el estudiante nunca accedió a la entrega
• CREATED, si el estudiante creó una entrega, pero aún no la envió.
• TURNED_IN, si el alumno envió su trabajo al profesor
• RETURNED, si el profesor le devolvió la entrega al alumno.
• RECLAIMED_BY_STUDENT, si el estudiante "anuló la entrega" de su trabajo.

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

• Se muestra el estado de entrega de las tareas dentro de tu complemento. Esto puede ayudar a los estudiantes a evitar posibles confusiones y asegurarse de no fallar al entregar una tarea por error.
• Se restringen los privilegios de edición de envíos. Si la tarea tiene el estado CREATED o RECLAIMED_BY_STUDENT, es posible que el estudiante pueda 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

Punto clave: Considera ofrecerles a los profesores la opción de habilitar o inhabilitar la devolución de calificaciones cuando creen un adjunto.

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 maxPoints, solo el primero de este tipo puede establecer la calificación de la tarea. No establezcas el valor de maxPoints o configúralo en cero para inhabilitar la devolución de calificaciones de un adjunto.

Cómo configurar la calificación de una entrega

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. Configura el campo pointsEarned para modificar la calificación de una entrega. El valor que se pasó en pointsEarned se convierte en una calificación preliminar visible para el profesor en la IU de Classroom. Los profesores pueden modificar la calificación preliminar antes de devolverles 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.

Advertencia: Las actualizaciones de calificaciones en la IU de Google Classroom no se aplican en tiempo real. Puede haber un retraso de hasta 30 segundos entre la recepción correcta de una calificación y la visualización en Classroom.

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

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

Además, ten en cuenta que puedes modificar el valor maxPoints de un AddOnAttachment ya creado emitiendo una solicitud PATCH al extremo addOnAttachments.

Cuándo establecer una calificación

Puedes 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 este puede modificar una calificación.

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

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

• Proporciona actualizaciones de calificaciones sin inconvenientes. Los profesores no necesitan realizar ninguna acción especial para que las calificaciones se propaguen en la IU de Classroom.
• Proporciona estadísticas en tiempo real sobre el progreso de una clase en una tarea. Si configuras las calificaciones a medida que los estudiantes completan archivos adjuntos, los profesores pueden tener una idea de la comprensión de sus estudiantes sin abrir cada entrega.

Ten en cuenta que este enfoque también permite un enfoque asíncrono para calificar la sincronización. Puedes consultar el extremo AddOnAttachmentStudentSubmission de forma periódica para detectar cuándo un estudiante envió su trabajo. Una vez que se envíe, configura la calificación de la entrega con las credenciales almacenadas.

Si no quieres cargar las credenciales del profesor durante una sesión de estudiante, puedes usar las credenciales del profesor activo cuando carguen su entrega en el iframe de Revisión del trabajo de los estudiantes. Sin embargo, es posible que esto no brinde una experiencia del usuario especialmente fluida, ya que las calificaciones de la IU de Classroom no se actualizan en tiempo real, y los profesores deberán abrir el iframe de revisión del trabajo de los estudiantes de las postulaciones.

Cómo detectar cambios en las calificaciones de las tareas

Punto clave: Considera verificar la configuración de calificación actual de una tarea antes de establecer la calificación de una entrega.

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

• Cambiar el valor en puntos asignado
• Cambiar el valor de maxPoints de una tarea
• Cambiar si se debe calificar la tarea

Para ver la configuración actual de las calificaciones 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 de maxPoints nulo o cero.

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