Adjuntos externos y entrega

Esta es la séptima explicación de la serie de instructivos sobre complementos de Classroom.

En esta explicación, agregarás comportamiento a una aplicación web para crear archivos adjuntos de complementos desde fuera de Google Classroom. Usa este comportamiento para permitir que los usuarios creen archivos adjuntos de complementos desde tu producto o sitio web existentes. Esto también es una gran incorporación a una integración de CourseWork, ya que diriges el tráfico existente a la experiencia del usuario mejorada que ofrece tu complemento sin cambiar su flujo. El proceso sugerido se presenta en la página de la guía Cómo crear archivos adjuntos fuera de Classroom.

También puedes agregar comportamiento a tu complemento para modificar una tarea con archivos adjuntos de complementos de forma programática. Puedes modificar cualquier tarea que tenga uno de los archivos adjuntos de tus complementos, independientemente de quién la haya creado. Esto es útil cuando se entregan tareas después de que un estudiante completó una actividad, lo que le indica al profesor que las tareas asignadas están completas y que el trabajo del estudiante está listo para su revisión.

Extiendes la versión final del complemento que admite content-type o activity-type attachments. En esta guía, se usa el archivo adjunto de tipo de contenido.

Agrega el permiso de OAuth de administración de tareas

Asegúrate de que tu aplicación solicite los siguientes permisos:

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student
  • https://www.googleapis.com/auth/classroom.coursework.students

El alcance de classroom.coursework.students no era necesario antes y se usa para crear o modificar tareas de CourseWork. Agrega este permiso a las listas de permisos del SDK de Google Workspace Marketplace, la pantalla de consentimiento de OAuth y el código del servidor de tu proyecto de Cloud.

Python

  SCOPES = [
    "https://www.googleapis.com/auth/classroom.addons.teacher",
    "https://www.googleapis.com/auth/classroom.addons.student",
    "https://www.googleapis.com/auth/classroom.coursework.students",
  ]

Crea una tarea en Classroom

Agrega botones a una página web sin iframe

El flujo que se describe en esta explicación permite que un usuario cree tareas y archivos adjuntos de Google Classroom desde un producto que no es de Google. En la práctica, es probable que sea tu sitio web o aplicación existente. En este ejemplo, debes crear una página web simulada para que actúe como un sitio externo. Necesitas un botón o un vínculo que, cuando se haga clic en él, abra una ruta nueva que realice el flujo CourseWork sugerido para crear una tarea nueva.

También deberás agregar un botón o un vínculo para permitir que el usuario acceda si aún no tienes uno. Necesitarás credenciales del usuario para realizar las solicitudes posteriores a la API, por lo que deben completar el protocolo de enlace de OAuth 2.0. Consulta la descripción general del acceso para obtener orientación específica.

Python

El ejemplo de Python proporcionado modifica la ruta /index que se presentó en el primer paso de la explicación.

<!-- /webapp/templates/index.html -->
<a href="clear-credentials.html">Logout</a>
<a href="start-auth-flow.html">Login</a>

<br>

<a href="create-coursework-assignment.html">Create a CourseWork Assignment</a>

Agrega una plantilla HTML para representar un destino en tu sitio web. Esta página representará el contenido que se adjuntará a tu tarea de CourseWork.

<!-- /webapp/templates/example-coursework-assignment.html -->
<h1>CourseWork assignment loaded!</h1>
<p>You've loaded a CourseWork assignment! It was created from an external web page.</p>

Crea un nuevo archivo de módulo de Python para controlar las rutas relacionadas con CourseWork. Esto es coursework_routes.py en nuestro ejemplo proporcionado. Agrega las siguientes tres rutas. Ten en cuenta que completarás parte del contenido más adelante.

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """

  # Check that the user is signed in. If not, perform the OAuth 2.0
  # authorization flow.
  credentials = get_credentials()

  if not credentials:
    return start_auth_flow("coursework_assignment_callback")

  # Construct the Google Classroom service.
  classroom_service = get_classroom_service()

  pass  # To be completed later.

@app.route("/example-coursework-assignment/<assignment_type>")
def example_coursework_assignment(assignment_type):
  """
  Renders the "example-coursework-assignment.html" template.
  """
  return flask.render_template(
      "example-coursework-assignment.html", assignment_type=assignment_type
  )

@app.route("/coursework-assignment-callback")
def coursework_assignment_callback():
  """
  Completes the OAuth 2.0 handshake and stores credentials in the session.
  This is identical to the callback introduced in the sign-in walkthrough,
  but redirects the user to the index page instead of the attachment
  discovery page.
  """
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE,
      scopes=SCOPES,
      state=flask.session["state"],
      redirect_uri=flask.url_for("coursework_assignment_callback", _external=True),
  )

  flow.fetch_token(authorization_response=flask.request.url)

  credentials = flow.credentials
  flask.session["credentials"] = session_credentials_to_dict(
      credentials
  )

  # Close the current window and redirect the user to the index page.
  return flask.render_template("close-me.html", redirect_destination="index")

Verifica la elegibilidad de un usuario para crear archivos adjuntos

Existen varios requisitos previos que un usuario debe cumplir para que puedas crear archivos adjuntos de complementos en su nombre. Para mayor comodidad, Google proporciona el método userProfiles.checkUserCapability para determinar si un usuario cumple con estos requisitos previos. Un usuario que cumple con los requisitos previos se denomina usuario apto.

Se agregó la verificación de elegibilidad a la implementación de la ruta de creación de CourseWork. Luego, prueba el campo allowed en la respuesta. En el caso de los usuarios aptos, sigue la lógica para crear una tarea con un archivo adjunto de complemento. De lo contrario, crea un Material de vínculo. Deberás conocer el ID del curso en el que el usuario quiere crear una tarea. Por lo general, le pedirás al usuario que especifique qué curso usar. Para simplificar, usamos un valor hard-coded en este ejemplo.

Python

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """
  # ... Check that the user is signed in and get the Classroom service ...

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.userProfiles()
      .checkUserCapability(
        userId="me",
        capability="CREATE_ADD_ON_ATTACHMENT",
        # The previewVersion is necessary while the method is available in the
        # Workspace Developer Preview Program.
        previewVersion="V1_20240930_PREVIEW",
      ).execute()
  )
  is_create_attachment_eligible = eligibility_response.get("allowed")

  if is_create_attachment_eligible:
    # See the "Create an assignment with add-on attachment for eligible users" section for implementation.
  if not is_create_attachment_eligible:
    # See the "Create a Link Material" section for implementation.

Crea una tarea con un archivo adjunto de complemento para los usuarios aptos

Si el usuario es apto para crear archivos adjuntos de complementos, haz lo siguiente:

  1. Envía una solicitud a la API para crear una tarea courseWork en Google Classroom sin archivos adjuntos.
  2. Extrae el id de la tarea recién creada.
  3. Crea un nuevo CourseWork AddOnAttachment.
  4. Envía una solicitud para crear un archivo adjunto de complemento en la tarea que acabas de crear en Google Classroom.

Python

# The ID of the course to which the assignment will be added.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

# /webapp/coursework_routes.py
if is_create_attachment_eligible:
  # Create an assignment.
  coursework = {
      "title": "My CourseWork Assignment with Add-on Attachment",
      "description": "Created using the Classroom CourseWork API.",
      "workType": "ASSIGNMENT",
      "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
  }

  # Issue a request to create the assignment.
  create_assignment_response = (
      classroom_service.courses()
      .courseWork()
      .create(courseId=course_id, body=coursework)
      .execute()
  )

  # Create an add-on attachment that links to the selected content and
  # associate it with the new assignment.
  content_url = flask.url_for(
      "example_coursework_assignment",
      assignment_type="add-on-attachment",
      _scheme="https",
      _external=True,
  )

  # Construct an AddOnAttachment instance.
  attachment = {
      "teacherViewUri": {"uri": content_url},
      "studentViewUri": {"uri": content_url},
      "title": f'Test Attachment for Assignment {create_assignment_response.get("id")}',
  }

  # Issue a request to create the attachment.
  add_on_attachment_response = (
      classroom_service.courses()
      .courseWork()
      .addOnAttachments()
      .create(
          courseId=course_id,
          itemId=create_assignment_response.get("id"),  # ID of the new assignment.
          body=attachment,
      )
      .execute()
  )

Si el usuario no es apto para crear archivos adjuntos de complementos, crea un material de vínculo. Para ello, sigue estos pasos:

Python

# The ID of the course to which the assignment will be added.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

if not is_create_attachment_eligible:
    coursework = {
        "title": "My CourseWork Assignment with Link Material",
        "description": "Created using the Classroom CourseWork API.",
        "workType": "ASSIGNMENT",
        "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
        # Specify the URL for your content as a Link Material.
        "materials": [
            {
                "link": {
                    "url": flask.url_for(
                        "example_coursework_assignment",
                        assignment_type="link-material",
                        _scheme="https",
                        _external=True,
                    )
                }
            }
        ],
    }

    # Issue a request to create the assignment.
    assignment_response = (
        classroom_service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )

Cómo modificar una tarea ya creada

Puedes acceder a cualquier elemento de la transmisión de Google Classroom, modificarlo, entregarlo, recuperarlo o devolverlo, independientemente de quién lo haya creado, y realizar cambios en él. Los elementos de la sección Novedades son cualquier Announcement, tarea CourseWork o CourseWorkMaterial.

Para demostrarlo, agregarás una ruta para modificar un elemento de transmisión determinado. Usa este método para verificar que puedes acceder a los elementos de transmisión que creaste con la API y que creó un profesor a través de la IU de Google Classroom, y modificarlos.

Agrega un vínculo o botón más a la página web que editaste por primera vez en esta explicación. Se debería abrir una ruta nueva para modificar una tarea de CourseWork.

Python

En el ejemplo de Python proporcionado, se modifica la ruta /index que se modificó antes en esta explicación.

<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>

Crea una ruta nueva para controlar las rutas relacionadas con CourseWork. Esto se encuentra en el archivo coursework_routes.py de nuestro ejemplo proporcionado.

# Check that the user is signed in.
credentials = get_credentials()

if not credentials:
  return start_auth_flow("coursework_assignment_callback")

# Get the Google Classroom service.
classroom_service = get_classroom_service()

# The ID of the course to which the assignment will be added.
# Ordinarily, you'll prompt the user to specify which course to use. For
# simplicity, we use a hard-coded value in this example.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.
assignment_id = 1234567890  # TODO(developer) Replace with an actual assignment ID.

# Retrieve details about the CourseWork assignment.
get_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .get(courseId=course_id, id=assignment_id)
    .execute()
)

# Alter the current title.
assignment_title = f"{get_coursework_response.get('title')} (Modified by API request)"

# Issue a request to modify the assignment.
modify_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .patch(
        courseId=course_id,
        id=assignment_id,
        updateMask="title",
        body={"title": assignment_title},
    )
    .execute()
)

Prueba el complemento

Para que sea sencillo, los ejemplos proporcionados usan identificadores de tareas y asignaturas codificados. Para obtener estos identificadores, realiza solicitudes con credenciales de profesor a los métodos get y list de los recursos courses y courseWork. También se muestran en la respuesta cuando se crean tareas de courseWork.

Ejecuta el servidor, navega a la página de índice y accede como usuario de profesor sin una licencia de Google Workspace for Education Teaching & Learning o Plus. Puedes activar o desactivar el estado de la licencia de un usuario desde la Consola del administrador de tu dominio de prueba.Haz clic en el botón Create a CourseWork Assignment, abre la IU de Google Classroom y verifica que se haya creado una tarea con un archivo adjunto de material de vínculo. El archivo adjunto debe mostrar el título de la página web vinculada y una URL.

Prueba la creación de archivos adjuntos de complementos

Regresa a la página principal y accede como usuario profesor con una licencia de Google Workspace for Education Teaching and Learning o Plus. Haz clic en el botón Create a CourseWork Assignment, abre la IU de Google Classroom y verifica que se haya creado una tarea con un archivo adjunto de complemento. El archivo adjunto debe mostrar el nombre de la aplicación del complemento y el título especificado en el código.

Prueba la modificación de la tarea

Regresa a la página principal y asegúrate de haber accedido como usuario con una licencia de profesor con Teaching and Learning o Plus. Haz clic en el botón Modificar una tarea de CourseWork, vuelve a la IU de Google Classroom y verifica que se haya modificado el título de la tarea.

¡Felicitaciones! Completaste la serie de instructivos.