Cómo interactuar con archivos adjuntos

En esta página, se analizan los detalles de la 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

Para crear un archivo adjunto, emite una solicitud CREATE al extremo courses.*.addOnAttachments.create apropiado. Tu solicitud debe incluir una instancia de AddOnAttachment en el cuerpo de la solicitud.

Los siguientes campos son obligatorios cuando se crea un archivo adjunto:

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

Te recomendamos que incluyas algunos de los siguientes campos opcionales:

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

Consulta la referencia de recursos de AddOnAttachment para obtener más detalles sobre estos campos.

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 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 estudiantes inicia la studentWorkReviewUri. La solicitud incluye los siguientes parámetros de consulta: 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 una entrega de un estudiante.

Cómo detectar el estado del 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 (pointsEarned) y el estado actual (postSubmissionState) del envío. 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 estudiante envió su trabajo al profesor.
• RETURNED, si el profesor devolvió la tarea al estudiante.
• RECLAIMED_BY_STUDENT, si el estudiante “retiró” 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 muestra. 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 a asegurarse de no olvidar entregar una tarea por error.
• Restringir 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

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 archivo adjunto de tipo de actividad que proporciona un valor maxPoints, solo el primer archivo adjunto de este tipo puede establecer la calificación de la tarea. Deja el valor de maxPoints sin establecer o configúralo en cero para inhabilitar la transferencia de calificaciones para un archivo adjunto.

Cómo establecer la calificación de una entrega

Para modificar el envío 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 una entrega. El valor que se pasa en pointsEarned se convierte en una calificación de borrador que el profesor puede ver 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 las calificaciones en la IU de Classroom para obtener detalles sobre cómo se presentan las calificaciones a los profesores.

Ten en cuenta que puedes establecer la calificación con pointsEarned solo si se cumple lo siguiente:

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

Ten en cuenta también que puedes modificar el valor maxPoints de un AddOnAttachment que ya se creó si emites una solicitud PATCH al extremo addOnAttachments.

Cuándo establecer una calificación

Puedes elegir cuándo se devuelve una calificación 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 del complemento 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 de trabajos de los estudiantes.

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

• Proporcionar 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 a través de una tarea. Si establecen calificaciones a medida que los estudiantes completan los archivos adjuntos, los profesores pueden tener una idea de su comprensión sin abrir cada envío.

Ten en cuenta que este enfoque también permite un enfoque asíncrono para la sincronización de calificaciones. Puedes sondear 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 de trabajos 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án abrir el iframe de Revisión de trabajos de los estudiantes de cada entrega.

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. Estos cambios pueden incluir lo siguiente:

• Cambiar el valor de puntos asignado
• Cambiar el valor maxPoints de una tarea
• Cambiar si la tarea debe calificarse

Para ver la configuración de calificación actual 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 enviaste una calificación a Classroom, usa el extremo courses.courseWork.addOnAttachments.studentSubmissions para recuperar o alterar la calificación de un archivo adjunto de complemento. El valor de la calificación se establece con el campo pointsEarned. Considera verificar este valor y, si es necesario, actualizarlo si tu producto permite que los profesores editen la puntuación de un estudiante para una actividad en particular.