Archivos adjuntos de tipo de contenido

Este es el cuarto recorrido de la serie de recorridos de los complementos de Classroom.

En este recorrido, interactúas con la API de Google Classroom para crear archivos adjuntos. Proporcionas rutas para que los usuarios vean el contenido de los archivos adjuntos. Las vistas difieren según el rol del usuario en la clase. En este recorrido, se abordan los archivos adjuntos de tipo de contenido, que no requieren que los estudiantes envíen contenido.

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

• Recuperar y usar los siguientes parámetros de consulta de complementos:
  • addOnToken: Es un token de autorización que se pasa a la vista de descubrimiento de archivos adjuntos.
  • itemId: Es un identificador único para CourseWork, CourseWorkMaterial o Announcement que recibe el archivo adjunto del complemento.
  • itemType: Puede ser "courseWork", "courseWorkMaterials" o "announcement".
  • courseId: Es un identificador único para el curso de Google Classroom en el que se crea la tarea.
  • attachmentId: Es un identificador único que Google Classroom asigna a un archivo adjunto del complemento después de la creación.
• Implementar almacenamiento persistente para archivos adjuntos de tipo de contenido
• Proporcionar rutas para crear archivos adjuntos y publicar los iframes de la vista del profesor y la vista del estudiante
• Enviar las siguientes solicitudes a la API de complementos de Google Classroom:
  • Crear un archivo adjunto nuevo
  • Obtener el contexto del complemento, que identifica si el usuario que accedió es un estudiante o un profesor

Una vez que termines, podrás crear archivos adjuntos de tipo de contenido en las tareas a través de la IU de Google Classroom cuando accedas como profesor. Los profesores y los estudiantes de la clase también pueden ver el contenido.

Habilita la API de Classroom

Realiza llamadas a la API de Classroom a partir de este paso. La API debe estar habilitada para tu proyecto de Google Cloud antes de que puedas realizar llamadas a ella. Navega a la entrada de la biblioteca de la API de Google Classroom y elige Habilitar.

Controla los parámetros de consulta de la vista de descubrimiento de archivos adjuntos

Como se mencionó anteriormente, Google Classroom pasa parámetros de consulta cuando carga la vista de descubrimiento de archivos adjuntos en el iframe:

• courseId: Es el ID del curso actual de Classroom.
• itemId: Es un identificador único para CourseWork, CourseWorkMaterial o Announcement que recibe el archivo adjunto del complemento.
• itemType: Puede ser "courseWork", "courseWorkMaterials" o "announcement".
• addOnToken: Es un token que se usa para autorizar ciertas acciones de complementos de Classroom.
• login_hint: Es el ID de Google del usuario actual.

En este recorrido, se abordan courseId, itemId, itemType y addOnToken. Conserva y pasa estos elementos cuando realices llamadas a la API de Classroom.

Al igual que en el paso anterior del recorrido, almacena los valores de los parámetros de consulta pasados en nuestra sesión. Es importante que lo hagamos cuando se abra por primera vez la vista de descubrimiento de archivos adjuntos, ya que esta es la única oportunidad para que Classroom pase estos parámetros de consulta.

# Retrieve the itemId, courseId, and addOnToken query parameters.
if flask.request.args.get("itemId"):
    flask.session["itemId"] = flask.request.args.get("itemId")
if flask.request.args.get("itemType"):
    flask.session["itemType"] = flask.request.args.get("itemType")
if flask.request.args.get("courseId"):
    flask.session["courseId"] = flask.request.args.get("courseId")
if flask.request.args.get("addOnToken"):
    flask.session["addOnToken"] = flask.request.args.get("addOnToken")

Agrega almacenamiento persistente para archivos adjuntos de tipo de contenido

Necesitas un registro local de los archivos adjuntos creados. Esto te permite buscar el contenido que seleccionó el profesor con los identificadores que proporciona Classroom.

Configura un esquema de base de datos para un Attachment. Nuestro ejemplo proporcionado presenta archivos adjuntos que muestran una imagen y una leyenda. Un Attachment contiene los siguientes atributos:

• attachment_id: Es un identificador único para un archivo adjunto. Classroom lo asigna y se muestra en la respuesta cuando se crea un archivo adjunto.
• image_filename: Es el nombre de archivo local de la imagen que se mostrará.
• image_caption: Es la leyenda que se mostrará con la imagen.

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

Configura rutas nuevas

Comienza este paso del recorrido configurando algunas páginas nuevas en nuestra aplicación. Esto permite que un usuario cree y vea contenido a través de nuestro complemento.

Agrega rutas de creación de archivos adjuntos

Necesitas páginas para que el profesor seleccione contenido y envíe solicitudes de creación de archivos adjuntos. Implementa la ruta /attachment-options para mostrar las opciones de contenido que el profesor puede seleccionar. También necesitas plantillas para las páginas de selección de contenido y confirmación de creación. Nuestros ejemplos proporcionados contienen plantillas para estos elementos y también pueden mostrar las solicitudes y respuestas de la API de Classroom.

Ten en cuenta que, como alternativa, puedes modificar tu página de destino de la vista de descubrimiento de archivos adjuntos existente para mostrar las opciones de contenido en lugar de crear la nueva página /attachment-options. Te recomendamos que crees una página nueva para este ejercicio, de modo que conserves el comportamiento de SSO implementado en el segundo paso del recorrido, como la revocación de los permisos de la app. Esto debería ser útil a medida que compilas y pruebas tu complemento.

Un profesor puede seleccionar un pequeño conjunto de imágenes con leyendas en nuestro ejemplo proporcionado. Proporcionamos cuatro imágenes de lugares famosos cuyas leyendas se derivan de los nombres de archivo.

@app.route("/attachment-options", methods=["GET", "POST"])
def attachment_options():
    """
    Render the attachment options page from the "attachment-options.html"
    template.

    This page displays a grid of images that the user can select using
    checkboxes.
    """

    # A list of the filenames in the static/images directory.
    image_filenames = os.listdir(os.path.join(app.static_folder, "images"))

    # The image_list_form_builder method creates a form that displays a grid
    # of images, checkboxes, and captions with a Submit button. All images
    # passed in image_filenames will be shown, and the captions will be the
    # title-cased filenames.

    # The form must be built dynamically due to limitations in WTForms. The
    # image_list_form_builder method therefore also returns a list of
    # attribute names in the form, which will be used by the HTML template
    # to properly render the form.
    form, var_names = image_list_form_builder(image_filenames)

    # If the form was submitted, validate the input and create the attachments.
    if form.validate_on_submit():

        # Build a dictionary that maps image filenames to captions.
        # There will be one dictionary entry per selected item in the form.
        filename_caption_pairs = construct_filename_caption_dictionary_list(
            form)

        # Check that the user selected at least one image, then proceed to
        # make requests to the Classroom API.
        if len(filename_caption_pairs) > 0:
            return create_attachments(filename_caption_pairs)
        else:
            return flask.render_template(
                "create-attachment.html",
                message="You didn't select any images.",
                form=form,
                var_names=var_names)

    return flask.render_template(
        "attachment-options.html",
        message=("You've reached the attachment options page. "
                "Select one or more images and click 'Create Attachment'."),
        form=form,
        var_names=var_names,
    )

Envía solicitudes de creación de archivos adjuntos

Ahora que sabes qué contenido desea adjuntar el profesor, envía solicitudes a la API de Classroom para crear archivos adjuntos en nuestra tarea. Almacena los detalles de los archivos adjuntos en tu base de datos después de recibir una respuesta de la API de Classroom.

Para comenzar, obtén una instancia del servicio de Classroom:

def create_attachments(filename_caption_pairs):
    """
    Create attachments and show an acknowledgement page.

    Args:
        filename_caption_pairs: A dictionary that maps image filenames to
            captions.
    """
    # Get the Google Classroom service.
    classroom_service = googleapiclient.discovery.build(
        serviceName="classroom",
        version="v1",
        credentials=credentials)

Envía una solicitud CREATE al courses.courseWork.addOnAttachments extremo. Para cada imagen seleccionada por el profesor, primero crea un AddOnAttachment objeto:

# Create a new attachment for each image that was selected.
attachment_count = 0
for key, value in filename_caption_pairs.items():
    attachment_count += 1

    # Create a dictionary with values for the AddOnAttachment object fields.
    attachment = {
        # Specifies the route for a teacher user.
        "teacherViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True),
        },
        # Specifies the route for a student user.
        "studentViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True)
        },
        # The title of the attachment.
        "title": f"Attachment {attachment_count}",
    }

Se deben proporcionar, al menos, los campos teacherViewUri, studentViewUri y title para cada archivo adjunto. teacherViewUri y studentViewUri representan las URLs que se cargan cuando el archivo adjunto se abre con el tipo de usuario respectivo.

Envía el objeto AddOnAttachment en el cuerpo de una solicitud al extremo addOnAttachments adecuado. Proporciona los identificadores courseId, itemId, itemType y addOnToken con cada solicitud.

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

# Issue a request to create the attachment.
resp = parent.addOnAttachments().create(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    addOnToken=flask.session["addOnToken"],
    body=attachment).execute()

Crea una entrada para este archivo adjunto en tu base de datos local para que puedas cargar el contenido correcto más adelante. Classroom muestra un valor id único en la respuesta a la solicitud de creación, por lo que debes usarlo como clave primaria en nuestra base de datos. Ten en cuenta también que Classroom pasa el parámetro de consulta attachmentId cuando se abren las vistas del profesor y del estudiante:

# Store the value 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)
db.session.add(new_attachment)
db.session.commit()

Considera enrutar al usuario a una página de confirmación en este punto, reconociendo que creó archivos adjuntos correctamente.

Permite archivos adjuntos desde tu complemento

Ahora es un buen momento para agregar las direcciones adecuadas al campo Prefijos de URI de archivos adjuntos permitidos en la página Configuración de la app del SDK de Google Workspace Marketplace. Tu complemento solo puede crear archivos adjuntos a partir de uno de los prefijos de URI que se enumeran en esta página. Esta es una medida de seguridad para ayudar a reducir la posibilidad de ataques de intermediario.

El enfoque más simple es proporcionar tu dominio de nivel superior en este campo, por ejemplo, https://example.com. https://localhost:<your port number>/ funcionaría si usas tu máquina local como servidor web.

Agrega rutas para las vistas del profesor y del estudiante

Hay cuatro iframes en los que se puede cargar un complemento de Google Classroom. Hasta ahora, solo compilaste rutas que publican el iframe de la vista de descubrimiento de archivos adjuntos. A continuación, agrega rutas para publicar también los iframes de la vista del profesor y del estudiante.

El iframe de la vista del profesor es necesario para mostrar una vista previa de la experiencia del estudiante, pero, de manera opcional, puede incluir información adicional o funciones de edición.

La vista del estudiante es la página que se presenta a cada estudiante cuando abre un archivo adjunto del complemento.

Para este ejercicio, crea una sola ruta /load-content-attachment que publique la vista del profesor y la vista del estudiante. Usa los métodos de la API de Classroom para determinar si el usuario es un profesor o un estudiante cuando se carga la página.

@app.route("/load-content-attachment")
def load_content_attachment():
    """
    Load the attachment for the user's role."""

    # Since this is a landing page for the Teacher and Student View iframes, we
    # need to preserve the incoming query parameters.
    if flask.request.args.get("itemId"):
        flask.session["itemId"] = flask.request.args.get("itemId")
    if flask.request.args.get("itemType"):
        flask.session["itemType"] = flask.request.args.get("itemType")
    if flask.request.args.get("courseId"):
        flask.session["courseId"] = flask.request.args.get("courseId")
    if flask.request.args.get("attachmentId"):
        flask.session["attachmentId"] = flask.request.args.get("attachmentId")

Ten en cuenta que también debes autenticar al usuario en este punto. También debes controlar el parámetro de consulta login_hint aquí y enrutar al usuario a tu flujo de autorización si es necesario. Consulta los detalles de la guía de acceso que se analizaron en los recorridos anteriores para obtener más información sobre este flujo.

Luego, envía una solicitud al extremo getAddOnContext que coincida con el tipo de elemento.

# Create an instance of the Classroom service.
classroom_service = googleapiclient.discovery.build(
    serviceName="classroom"
    version="v1",
    credentials=credentials)

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

addon_context_response = parent.getAddOnContext(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"]).execute()

Este método muestra información sobre el rol del usuario actual en la clase. Modifica la vista que se presenta al usuario según su rol. Se completa exactamente uno de los studentContext o teacherContext campos en el objeto de respuesta. Examínalos para determinar cómo dirigirte al usuario.

En cualquier caso, usa el valor del parámetro de consulta attachmentId para saber qué archivo adjunto recuperar de nuestra base de datos. Este parámetro de consulta se proporciona cuando se abren las URIs de la vista del profesor o del estudiante.

# Determine which view we are in by testing the returned context type.
user_context = "student" if addon_context_response.get(
    "studentContext") else "teacher"

# Look up the attachment in the database.
attachment = Attachment.query.get(flask.session["attachmentId"])

# Set the text for the next page depending on the user's role.
message_str = f"I see that you're a {user_context}! "
message_str += (
    f"I've loaded the attachment with ID {attachment.attachment_id}. "
    if user_context == "teacher" else
    "Please enjoy this image of a famous landmark!")

# Show the content with the customized message text.
return flask.render_template(
    "show-content-attachment.html",
    message=message_str,
    image_filename=attachment.image_filename,
    image_caption=attachment.image_caption,
    responses=response_strings)

Prueba el complemento

Para probar la creación de archivos adjuntos, completa los siguientes pasos:

• Accede a [Google Classroom] como uno de tus usuarios de prueba profesores.
• Navega a la pestaña Trabajo en clase y crea una tarea nueva.
• Haz clic en el botón Complementos debajo del área de texto y, luego, selecciona tu complemento. Se abrirá el iframe y el complemento cargará el URI de configuración de archivos adjuntos que especificaste en la página Configuración de la app del SDK de Google Workspace Marketplace.
• Elige un contenido para adjuntar a la tarea.
• Cierra el iframe después de que se complete el flujo de creación de archivos adjuntos.

Deberías ver una tarjeta de archivo adjunto en la IU de creación de tareas en Google Google Classroom. Haz clic en la tarjeta para abrir el iframe de la vista del profesor y confirma que aparece el archivo adjunto correcto. Haz clic en el botón Asignar.

Para probar la experiencia del estudiante, completa los siguientes pasos:

• Luego, accede a Classroom como usuario de prueba estudiante en la misma clase que el usuario de prueba profesor.
• Busca la tarea de prueba en la pestaña Trabajo en clase.
• Expande la tarea y haz clic en la tarjeta de archivo adjunto para abrir el iframe de la vista del estudiante.

Confirma que aparece el archivo adjunto correcto para el estudiante.

¡Felicitaciones! Ya puedes continuar con el siguiente paso: crear archivos adjuntos de tipo de actividad.