Calificaciones de archivos adjuntos y devoluciones de calificaciones

Esta es la sexta explicación de la serie de instructivos sobre complementos de Classroom.

En esta explicación, modificas el ejemplo del paso anterior para producir un archivo adjunto de tipo de actividad calificado. También puedes devolver una calificación a Google Classroom de manera programática, que aparece en el libro de calificaciones del profesor como una calificación preliminar.

Esta explicación difiere ligeramente de las demás de la serie, ya que se presentan dos enfoques posibles para enviar las calificaciones a Classroom. Ambos tienen impactos claros en el desarrollador y la experiencia del usuario. Ten en cuenta ambos cuando diseñes tu complemento de Classroom. Lee nuestra página de la guía para interactuar con archivos adjuntos para obtener más información sobre las opciones de implementación.

Ten en cuenta que las funciones de calificación de la API son opcionales. Se pueden usar con cualquier adjunto de tipo de actividad.

En el transcurso de esta explicación, completarás las siguientes tareas:

• Modifica las solicitudes de creación de archivos adjuntos anteriores a la API de Classroom para establecer también el denominador de la calificación del archivo adjunto.
• Asigna una puntuación de forma programática a la entrega del estudiante y establece el numerador de la calificación del archivo adjunto.
• Implementa dos enfoques para pasar la calificación de la entrega a Classroom con credenciales de profesor sin conexión o de acceso.

Una vez que finalicen, las calificaciones aparecerán en el libro de calificaciones de Classroom después de que se active el comportamiento de devolución. El momento exacto en que esto sucede depende del enfoque de implementación.

A los efectos de este ejemplo, reutiliza la actividad del recorrido anterior, en la que se le muestra a un estudiante una imagen de un lugar famoso y se le solicita que ingrese su nombre. Asigna marcas completas para el archivo adjunto si el estudiante ingresa el nombre correcto; de lo contrario, asigna cero.

Información sobre la función de calificación de la API de complementos de Classroom

Tu complemento puede establecer el numerador y el denominador de la calificación de un archivo adjunto. Estos se establecen, respectivamente, con los valores pointsEarned y maxPoints en la API. Una tarjeta de archivo adjunto en la IU de Classroom muestra el valor maxPoints cuando se establece.

Figura 1: IU de creación de tareas con tres tarjetas adjuntas de complementos que tienen configurado maxPoints

La API de complementos de Classroom te permite establecer la configuración y la puntuación obtenida para las calificaciones de archivos adjuntos. Estas no son las mismas que las calificaciones de tareas. Sin embargo, la configuración de la calificación de la tarea sigue la configuración de la calificación del archivo adjunto que tiene la etiqueta Sincronización de calificaciones en su tarjeta. Cuando el archivo adjunto “Sincronización de calificaciones” establece pointsEarned para una entrega de un estudiante, también establece la calificación preliminar del estudiante para la tarea.

Por lo general, el primer archivo adjunto que se agregó a la tarea que establece maxPoints recibe la etiqueta “Sincronización de calificaciones”. Consulta el ejemplo de la IU de creación de tareas que se muestra en la Figura 1 para ver un ejemplo de la etiqueta “Sincronización de calificaciones”. Ten en cuenta que la tarjeta “Archivo adjunto 1” tiene la etiqueta “Sincronización de calificaciones” y que la calificación de la tarea en el cuadro rojo se actualizó a 50 puntos. También ten en cuenta que, aunque la Figura 1 muestra tres tarjetas de archivos adjuntos, solo una tiene la etiqueta “Sincronización de calificaciones”. Esta es una limitación clave de la implementación actual: solo un archivo adjunto puede tener la etiqueta “Sincronización de calificaciones”.

Si hay varios archivos adjuntos que establecieron maxPoints, quitar el archivo adjunto con "Sincronización de calificaciones" no habilita "Sincronización de calificaciones" en ninguno de los archivos adjuntos restantes. Si agregas otro archivo adjunto que establezca maxPoints, se habilita la sincronización de calificaciones en el archivo adjunto nuevo, y la calificación máxima de la tarea se ajusta para que coincida. No hay un mecanismo para ver de forma programática qué archivo adjunto tiene la etiqueta “Sincronización de calificaciones” ni para ver cuántos archivos adjuntos tiene una tarea en particular.

Cómo establecer la calificación máxima de un archivo adjunto

En esta sección, se describe cómo configurar el denominador para una calificación de archivo adjunto, es decir, la puntuación máxima posible que todos los estudiantes pueden obtener por sus envíos. Para ello, establece el valor maxPoints del archivo adjunto.

Solo se necesita una pequeña modificación en nuestra implementación existente para habilitar las funciones de calificación. Cuando crees un archivo adjunto, agrega el valor maxPoints en el mismo objeto AddOnAttachment que contiene studentWorkReviewUri, teacherViewUri y otros campos de archivos adjuntos.

Ten en cuenta que la puntuación máxima predeterminada para una tarea nueva es de 100. Te sugerimos que establezcas maxPoints en un valor distinto de 100 para que puedas verificar que las calificaciones se establezcan correctamente. Establece maxPoints en 50 como demostración:

attachment = {
    # Specifies the route for a teacher user.
    "teacherViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True),
    },
    # Specifies the route for a student user.
    "studentViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True)
    },
    # Specifies the route for a teacher user when the attachment is
    # loaded in the Classroom grading view.
    "studentWorkReviewUri": {
        "uri":
            flask.url_for(
                "view_submission", _scheme='https', _external=True)
    },
    # Sets the maximum points that a student can earn for this activity.
    # This is the denominator in a fractional representation of a grade.
    "maxPoints": 50,
    # The title of the attachment.
    "title": f"Attachment {attachment_count}",
}

Para los fines de esta demostración, también almacenarás el valor maxPoints en tu base de datos local de archivos adjuntos; esto evita tener que realizar una llamada a la API adicional más adelante cuando califiques las entregas de los estudiantes. Sin embargo, ten en cuenta que es posible que los profesores alteren la configuración de la calificación de las tareas independientemente de tu complemento. Envía una solicitud GET al extremo courses.courseWork para ver el valor maxPoints a nivel de la tarea. Cuando lo hagas, pasa el itemId en el campo CourseWork.id.

Ahora, actualiza tu modelo de base de datos para que también contenga el valor maxPoints del archivo adjunto. Recomendamos usar el valor maxPoints de la respuesta CREATE:

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    # Store the maxPoints value returned in the response.
    max_points=int(resp.get("maxPoints")))
db.session.add(new_attachment)
db.session.commit()

El archivo adjunto ahora tiene una calificación máxima. Deberías poder probar este comportamiento ahora. Agrega un archivo adjunto a una tarea nueva. Observa que la tarjeta del archivo adjunto muestra la etiqueta “Sincronización de calificaciones” y cambia el valor de “Puntos” de la tarea.

Cómo establecer la calificación de una entrega de estudiante en Classroom

En esta sección, se describe cómo configurar el numerador para una calificación de archivo adjunto, es decir, la puntuación de un estudiante individual para el archivo adjunto. Para ello, establece el valor pointsEarned de la entrega de un estudiante.

Ahora tienes una decisión importante que tomar: ¿cómo debe tu complemento emitir una solicitud para configurar pointsEarned?

El problema es que la configuración de pointsEarned requiere el permiso de OAuth teacher. No debes otorgar el permiso teacher a los usuarios estudiantes, ya que esto podría generar un comportamiento inesperado cuando los estudiantes interactúen con tu complemento, como cargar el iframe de la vista del profesor en lugar del iframe de la vista del estudiante. Por lo tanto, tienes dos opciones para configurar pointsEarned:

• Con las credenciales del profesor que accedió
• Usa credenciales de profesor almacenadas (sin conexión).

En las siguientes secciones, se analizan las compensaciones de cada enfoque antes de demostrar cada implementación. Ten en cuenta que nuestros ejemplos muestran ambos enfoques para pasar una calificación a Classroom. Consulta las instrucciones específicas para cada idioma a continuación para saber cómo seleccionar un enfoque cuando ejecutes los ejemplos proporcionados:

Establece calificaciones con las credenciales del profesor que accedió

Usa las credenciales del usuario que accedió a fin de emitir la solicitud para configurar pointsEarned. Esto debería parecer bastante intuitivo, ya que refleja el resto de la implementación hasta el momento y requiere poco esfuerzo para realizarlo.

Sin embargo, ten en cuenta que el profesor solo interactúa con la entrega del alumno en el iframe de Revisión del trabajo de los alumnos. Esto tiene algunas implicaciones importantes:

• No se propagarán calificaciones en Classroom hasta que el profesor realice una acción en la IU de Classroom.
• Es posible que un profesor deba abrir cada entrega de los estudiantes para propagar todas sus calificaciones.
• Hay una breve demora entre el momento en que Classroom recibe la calificación y su aparición en la IU de Classroom. El retraso es generalmente de cinco a diez segundos, pero puede ser de hasta 30 segundos.

La combinación de estos factores significa que los profesores pueden tener que realizar un trabajo manual considerable y que consume mucho tiempo para completar las calificaciones de una clase.

Para implementar este enfoque, agrega una llamada a la API adicional a tu ruta existente de revisión de trabajos de estudiantes.

Después de recuperar los registros de entrega y archivo adjunto del estudiante, evalúa su entrega y almacena la calificación resultante. Establece la calificación en el campo pointsEarned de un objeto AddOnAttachmentStudentSubmission. Por último, emite una solicitud PATCH al extremo courses.courseWork.addOnAttachments.studentSubmissions con la instancia AddOnAttachmentStudentSubmission en el cuerpo de la solicitud. Ten en cuenta que también debemos especificar pointsEarned en el updateMask en nuestra solicitud PATCH:

# Look up the student's submission in our database.
student_submission = Submission.query.get(flask.session["submissionId"])

# Look up the attachment in the database.
attachment = Attachment.query.get(student_submission.attachment_id)

grade = 0

# See if the student response matches the stored name.
if student_submission.student_response.lower(
) == attachment.image_caption.lower():
    grade = attachment.max_points

# Create an instance of the Classroom service.
classroom_service = ch._credential_handler.get_classroom_service()

# Build an AddOnAttachmentStudentSubmission instance.
add_on_attachment_student_submission = {
    # Specifies the student's score for this attachment.
    "pointsEarned": grade,
}

# Issue a PATCH request to set the grade numerator for this attachment.
patch_grade_response = classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

Establece calificaciones con credenciales de profesores sin conexión

El segundo enfoque para establecer calificaciones requiere el uso de credenciales almacenadas para el profesor que creó el adjunto. Esta implementación requiere que compiles credenciales con los tokens de acceso y actualización de un profesor autorizado con anterioridad y, luego, uses estas credenciales para configurar pointsEarned.

Una ventaja fundamental de este enfoque es que las calificaciones se propagan sin requerir la acción del profesor en la IU de Classroom, lo que evita los problemas mencionados anteriormente. El resultado es que los usuarios finales perciben la experiencia de calificación como fluida y eficiente. Además, este enfoque te permite elegir el momento en el que devuelves las calificaciones, por ejemplo, cuando los estudiantes completan la actividad o de forma asíncrona.

Para implementar este enfoque, completa las siguientes tareas:

1. Modifica los registros de la base de datos de usuarios para almacenar un token de acceso.
2. Modifica los registros de la base de datos de archivos adjuntos para almacenar un ID de profesor.
3. Recupera las credenciales del profesor y, de forma opcional, compila una nueva instancia del servicio de Classroom.
4. Establece la calificación de una entrega.

A los efectos de esta demostración, establece la calificación cuando el estudiante complete la actividad, es decir, cuando envíe el formulario en la ruta de acceso de la vista del estudiante.

Modificar los registros de la base de datos del usuario para almacenar el token de acceso

Se requieren dos tokens únicos para realizar llamadas a la API: el token de actualización y el token de acceso. Si seguiste la serie de explicaciones hasta ahora, el esquema de la tabla User ya debería almacenar un token de actualización. Almacenar el token de actualización es suficiente cuando solo realizas llamadas a la API con el usuario que accedió, ya que recibes un token de acceso como parte del flujo de autenticación.

Sin embargo, ahora debes realizar llamadas como otra persona que no sea el usuario que accedió, lo que significa que el flujo de autenticación no está disponible. Por lo tanto, debes almacenar el token de acceso junto con el token de actualización. Actualiza el esquema de la tabla User para incluir un token de acceso:

# Database model to represent a user.
class User(db.Model):
    # The user's identifying information:
    id = db.Column(db.String(120), primary_key=True)
    display_name = db.Column(db.String(80))
    email = db.Column(db.String(120), unique=True)
    portrait_url = db.Column(db.Text())

    # The user's refresh token, which will be used to obtain an access token.
    # Note that refresh tokens will become invalid if:
    # - The refresh token has not been used for six months.
    # - The user revokes your app's access permissions.
    # - The user changes passwords.
    # - The user belongs to a Google Cloud organization
    #   that has session control policies in effect.
    refresh_token = db.Column(db.Text())

    # An access token for this user.
    access_token = db.Column(db.Text())

Luego, actualiza el código que crea o actualiza un registro User para que también almacene el token de acceso:

def save_credentials_to_storage(self, credentials):
    # Issue a request for the user's profile details.
    user_info_service = googleapiclient.discovery.build(
        serviceName="oauth2", version="v2", credentials=credentials)
    user_info = user_info_service.userinfo().get().execute()
    flask.session["username"] = user_info.get("name")
    flask.session["login_hint"] = user_info.get("id")

    # See if we have any stored credentials for this user. If they have used
    # the add-on before, we should have received login_hint in the query
    # parameters.
    existing_user = self.get_credentials_from_storage(user_info.get("id"))

    # If we do have stored credentials, update the database.
    if existing_user:
        if user_info:
            existing_user.id = user_info.get("id")
            existing_user.display_name = user_info.get("name")
            existing_user.email = user_info.get("email")
            existing_user.portrait_url = user_info.get("picture")

        if credentials and credentials.refresh_token is not None:
            existing_user.refresh_token = credentials.refresh_token
            # Update the access token.
            existing_user.access_token = credentials.token

    # If not, this must be a new user, so add a new entry to the database.
    else:
        new_user = User(
            id=user_info.get("id"),
            display_name=user_info.get("name"),
            email=user_info.get("email"),
            portrait_url=user_info.get("picture"),
            refresh_token=credentials.refresh_token,
            # Store the access token as well.
            access_token=credentials.token)

        db.session.add(new_user)

    db.session.commit()

Modifica los registros de la base de datos de archivos adjuntos para almacenar un ID de profesor

Si deseas establecer la calificación de una actividad, realiza una llamada para establecer a pointsEarned como profesor en el curso. Hay varias formas de hacerlo:

• Almacena una asignación local de las credenciales de los profesores a los IDs de los cursos. Sin embargo, ten en cuenta que es posible que el mismo profesor no siempre se asocie con un curso en particular.
• Emite solicitudes GET al extremo courses de la API de Classroom para obtener los profesores actuales. Luego, consulta los registros de usuarios locales para ubicar las credenciales de los profesores.
• Cuando crees un archivo adjunto de complemento, almacena un ID de profesor en la base de datos de archivos adjuntos local. Luego, recupera las credenciales del profesor del attachmentId que se pasó al iframe de la vista de estudiante.

En este ejemplo, se muestra la última opción, ya que estableces calificaciones cuando el estudiante completa un archivo adjunto de actividad.

Agrega un campo de ID de profesor a la tabla Attachment de tu base de datos:

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

    # The ID of the teacher that created the attachment.
    teacher_id = db.Column(db.String(120))

Luego, actualiza el código que crea o actualiza un registro Attachment para que también almacene el ID del creador:

# Store the attachment by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    max_points=int(resp.get("maxPoints")),
    teacher_id=flask.session["login_hint"])
db.session.add(new_attachment)
db.session.commit()

Cómo recuperar las credenciales del profesor

Busca la ruta que entrega el iframe de la vista del alumno. Inmediatamente después de almacenar la respuesta del estudiante en tu base de datos local, recupera las credenciales del profesor desde tu almacenamiento local. Esto debería ser sencillo, ya que realizaste la preparación en los dos pasos anteriores. También puedes usarlos para crear una instancia nueva del servicio de Classroom para el usuario profesor:

# Create an instance of the Classroom service using the tokens for the
# teacher that created the attachment.

# We're assuming that there are already credentials in the session, which
# should be true given that we are adding this within the Student View
# route; we must have had valid credentials for the student to reach this
# point. The student credentials will be valid to construct a Classroom
# service for another user except for the tokens.
if not flask.session.get("credentials"):
    raise ValueError(
        "No credentials found in session for the requested user.")

# Make a copy of the student credentials so we don't modify the original.
teacher_credentials_dict = deepcopy(flask.session.get("credentials"))

# Retrieve the requested user's stored record.
teacher_record = User.query.get(attachment.teacher_id)

# Apply the user's tokens to the copied credentials.
teacher_credentials_dict["refresh_token"] = teacher_record.refresh_token
teacher_credentials_dict["token"] = teacher_record.access_token

# Construct a temporary credentials object.
teacher_credentials = google.oauth2.credentials.Credentials(
    **teacher_credentials_dict)

# Refresh the credentials if necessary; we don't know when this teacher last
# made a call.
if teacher_credentials.expired:
    teacher_credentials.refresh(Request())

# Request the Classroom service for the specified user.
teacher_classroom_service = googleapiclient.discovery.build(
    serviceName=CLASSROOM_API_SERVICE_NAME,
    version=CLASSROOM_API_VERSION,
    credentials=teacher_credentials)

Cómo establecer la calificación de una entrega

El procedimiento a partir de aquí es idéntico al de usar las credenciales del profesor que accedió. Sin embargo, ten en cuenta que debes realizar la llamada con las credenciales del profesor que se recuperaron en el paso anterior:

# Issue a PATCH request as the teacher to set the grade numerator for this
# attachment.
patch_grade_response = teacher_classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

Prueba el complemento

Al igual que en la explicación anterior, crea una tarea con un archivo adjunto de tipo de actividad como profesor, envía una respuesta como estudiante y, luego, abre su entrega en el iframe de Revisión del trabajo de los estudiantes. Deberías poder ver la calificación en diferentes momentos según tu enfoque de implementación:

• Si decides pasar una calificación cuando el estudiante completó la actividad, deberías ver su calificación preliminar en la IU antes de abrir el iframe de Revisión del trabajo del estudiante. También puedes verla en la lista de estudiantes cuando abres la tarea y en el cuadro “Calificación” junto al iframe de Revisión del trabajo del estudiante.
• Si decidiste enviar una calificación cuando el profesor abre el iframe de revisión del trabajo del alumno, la calificación debería aparecer en el cuadro “Calificación” poco después de que se cargue el iframe. Como se mencionó anteriormente, este proceso puede tardar hasta 30 segundos. Luego, la calificación del estudiante específico también debería aparecer en las otras vistas del libro de calificaciones de Classroom.

Confirma que aparezca la puntuación correcta para el estudiante.

¡Felicitaciones! Ya puedes pasar al siguiente paso: crear archivos adjuntos fuera de Google Classroom.