Crea archivos adjuntos fuera de Google Classroom

En esta guía, se explica cómo crear archivos adjuntos de complementos en tu sitio web o aplicación. Las interacciones son similares a las de crear tareas con los extremos de la API de CourseWork. Implementa este recorrido para permitir que los usuarios creen archivos adjuntos de complementos desde tu sitio web o aplicación.

Importante: Te recomendamos que implementes este flujo de creación de archivos adjuntos si ya creas tareas de CourseWork. Extender una implementación de CourseWork te permite convertir a muchos más usuarios en usuarios de tu complemento y requiere poco trabajo adicional.

Flujo de trabajo

En términos generales, el proceso de creación de archivos adjuntos sigue esta secuencia:

1. Un usuario docente abre tu sitio web o aplicación y selecciona un elemento de contenido para asignárselo a sus estudiantes.
2. Verifica que el usuario pueda crear archivos adjuntos de complementos.
3. Si el usuario no puede crear archivos adjuntos de complementos, crea una tarea de CourseWork con la URL del contenido seleccionado como un material de vínculo.
4. Si el usuario puede crear archivos adjuntos de complementos, haz lo siguiente:
   1. Crea una tarea.
   2. Crea un adjunto de complemento que vincule al contenido seleccionado y asócialo a la tarea nueva.
5. Informa al profesor que la tarea se creó correctamente.

Cada acción se describe en las siguientes secciones.

Comprueba si un usuario puede crear archivos adjuntos de complementos

Puedes crear archivos adjuntos de complementos en nombre de un usuario apto. Un usuario apto es un usuario que es profesor en el curso en el que intentas crear tareas de CourseWork y tiene asignada la licencia de edición de Google Workspace for Education de Teaching & Learning o Education Plus.

Concepto principal: Es posible que la elegibilidad para crear archivos adjuntos de complementos sea diferente para cada usuario y puede cambiar con el tiempo. Siempre verifica la elegibilidad del usuario antes de intentar crear archivos adjuntos de complementos.

Importante: Las verificaciones de elegibilidad con la API de Classroom están en versión preliminar pública y disponibles en la versión preliminar V1_20240930_PREVIEW y versiones posteriores. Para usar los métodos de la API en la versión preliminar pública, debes formar parte del Programa de versión preliminar para desarrolladores de Google Workspace y realizar una configuración adicional más allá del uso típico de la API de Classroom.

Comienza por determinar si el usuario puede crear archivos adjuntos de complementos. Para ello, envía una solicitud al extremo userProfiles.checkUserCapability con el parámetro de capacidad CREATE_ADD_ON_ATTACHMENT. Inspecciona el campo booleano allowed en la respuesta. Un valor true indica que el usuario cumple con los requisitos para crear archivos adjuntos de complementos.

Advertencia: No se garantiza que se completen las solicitudes para crear archivos adjuntos de complementos para los usuarios con la capacidad de CREATE_ADD_ON_ATTACHMENT. Por ejemplo, un usuario con la capacidad recibirá un error de respuesta 403 si intentas crear archivos adjuntos de complementos en su nombre en un curso en el que el usuario no es profesor.

Python

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')
)
print('User eligibility for add-on attachment creation: '
      f'{is_create_attachment_eligible}.')

Cómo enrutar al usuario según su elegibilidad

La elegibilidad determina si puedes crear archivos adjuntos de complementos para un usuario.

Importante: Los complementos ofrecen ventajas significativas en la experiencia del usuario. Siempre crea archivos adjuntos de complementos para los usuarios que cumplen con los requisitos.

Usuario no apto

Si el usuario no puede crear archivos adjuntos de complementos, crea una nueva tarea CourseWork con la URL del contenido seleccionado por el usuario como Link.

Python

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.
    'maxPoints': 100,
    'materials': [
      {'link': {'url': my_content_url}}
    ]
  }

  assignment = (
    service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Link Material assignment created with ID: {assignment.get("id")}'
  )

La respuesta contiene una tarea del curso solicitado con el contenido adjunto. Los usuarios pueden hacer clic en Link para abrir el contenido de tu sitio en una pestaña nueva.

Figura 1: Vista del profesor de una tarea de CourseWork en borrador con material de vínculo.

Usuario apto

Haz lo siguiente si el usuario puede crear archivos adjuntos de complementos.

1. Crea una nueva tarea de CourseWork sin archivos adjuntos.
2. Crea un archivo adjunto del complemento.
   • Establece el itemId de AddOnAttachment en el id de la tarea recién creada.
   • Asegúrate de proporcionar URLs al contenido seleccionado por el usuario para cada vista que admitas.

Python

if is_create_attachment_eligible:
  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.
    'maxPoints': 100,
  }

  assignment = (
    classroom_service.courses()
    .courseWork()
    .create(courseId=course_id, body=coursework)
    .execute()
  )

  print(
    f'Empty assignment created with ID: {assignment.get("id")}'
  )

  attachment = {
    'teacherViewUri': {'uri': teacher_view_url},
    'studentViewUri': {'uri': student_view_url},
    'studentWorkReviewUri': {'uri': grade_student_work_url},
    'title': f'Test Attachment {test_label}',
  }

  add_on_attachment = (
    service.courses()
    .courseWork()
    .addOnAttachments()
    .create(
      courseId=course_id,
      itemId=assignment.get("id"),  # ID of the new assignment.
      body=attachment,
    )
    .execute()
  )

  print(
    f'Add-on attachment created with ID: {add_on_attachment.get("id")}'
  )

Nota: No se requiere un token de complemento si creas un archivo adjunto en una tarea que creaste.

El complemento aparece como una tarjeta de archivo adjunto en Classroom. Las URLs especificadas en la solicitud se abren en el iframe adecuado para cada vista.