Calificaciones de archivos adjuntos y devoluciones de calificaciones

Este es el sexto recorrido de la serie de recorridos de complementos de Classroom.

En este recorrido, modificas el ejemplo del paso anterior para producir un archivo adjunto de tipo de actividad calificado. También pasas una calificación a Google Classroom de forma programática, que aparece en el libro de calificaciones del profesor como una calificación de borrador.

Este recorrido difiere ligeramente de otros de la serie, ya que presenta dos enfoques posibles para pasar las calificaciones a Classroom. Ambos tienen impactos distintos en las experiencias del desarrollador y del usuario. Tenlos en cuenta cuando diseñes tu complemento de Classroom. Consulta nuestra página de 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 archivo adjunto de tipo de actividad.

En el transcurso de este recorrido, completarás lo siguiente:

• Modificar 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
• Calificar de forma programática la entrega del estudiante y establecer el numerador de la calificación del archivo adjunto
• Implementar dos enfoques para pasar la calificación de la entrega a Classroom con credenciales de profesor sin conexión o con acceso

Una vez que finalices, 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.

Para los fines de este ejemplo, vuelve a usar la actividad del recorrido anterior, en la que se le muestra a un estudiante una imagen de un monumento famoso y se le solicita que ingrese su nombre. Asigna la puntuación máxima al 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 estableció.

Figura 1: La IU de creación de tareas con tres tarjetas de archivos adjuntos de complementos que tienen maxPoints establecido.

La API de complementos de Classroom te permite configurar los parámetros de configuración y establecer la puntuación obtenida para las calificaciones de los archivos adjuntos. No son lo mismo que las calificaciones de las 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 de archivo adjunto. Cuando el archivo adjunto "Sincronización de calificaciones" establece pointsEarned para una entrega de un estudiante, también establece la calificación de borrador 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. Ten en cuenta también 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 tienen maxPoints establecido, quitar el archivo adjunto con "Sincronización de calificaciones" no habilita "Sincronización de calificaciones" en ninguno de los archivos adjuntos restantes. Agregar otro archivo adjunto que establezca maxPoints 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 ningún 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.

Establece la calificación máxima de un archivo adjunto

En esta sección, se describe cómo establecer el denominador para la calificación de un archivo adjunto, es decir, la puntuación máxima posible que todos los estudiantes pueden obtener por sus entregas. 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 maxPoints valor en el mismo AddOnAttachment objeto que contiene el studentWorkReviewUri, teacherViewUri, y otros campos de archivos adjuntos.

Ten en cuenta que la puntuación máxima predeterminada para una tarea nueva es 100. Te sugerimos que establezcas maxPoints en un valor que no sea 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 almacenas el valor maxPoints en tu base de datos de archivos adjuntos local. 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 modifiquen la configuración de la calificación de la tarea de forma independiente 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. Te recomendamos que uses 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 y observa que la tarjeta de archivo adjunto muestra la etiqueta "Sincronización de calificaciones" y que cambia el valor "Puntos" de la tarea.

Establece la calificación de la entrega de un estudiante en Classroom

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

Ahora tienes que tomar una decisión importante: ¿cómo debería tu complemento emitir una solicitud para establecer pointsEarned?

El problema es que establecer pointsEarned requiere el permiso de OAuthteacher. No debes otorgar el permiso teacher a los usuarios estudiantes. Esto podría generar un comportamiento inesperado cuando los estudiantes interactúan 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 establecer pointsEarned:

• Usar las credenciales del profesor conectado
• Usar credenciales de profesor almacenadas (sin conexión)

En las siguientes secciones, se analizan las ventajas y desventajas de cada enfoque antes de demostrar cada implementación. Ten en cuenta que nuestros ejemplos proporcionados demuestran ambos enfoques para pasar una calificación a Classroom. Consulta las instrucciones específicas del lenguaje que se indican a continuación para ver cómo seleccionar un enfoque cuando ejecutas los ejemplos proporcionados:

Establece calificaciones con las credenciales del profesor conectado

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

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

• No se propagan calificaciones en Classroom hasta que el profesor realiza una acción en la IU de Classroom.
• Es posible que un profesor deba abrir cada entrega del estudiante para propagar todas las calificaciones de los estudiantes.
• Hay una breve demora entre que Classroom recibe la calificación y su aparición en la IU de Classroom. Por lo general, la demora es 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 requiere mucho tiempo para propagar por completo las calificaciones de una clase.

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

Después de recuperar los registros de entrega y archivo adjunto del estudiante, evalúa la entrega del estudiante y almacena la calificación resultante. Establece la calificación en el pointsEarned campo de un AddOnAttachmentStudentSubmission objeto. Por último, emite una PATCH solicitud al courses.courseWork.addOnAttachments.studentSubmissions extremo con la AddOnAttachmentStudentSubmission instancia en el cuerpo de la solicitud. Ten en cuenta que también debemos especificar pointsEarned en 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 profesor sin conexión

# 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())

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()

# 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))

# 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()

# 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)

# 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()