Los profesores que aprovechan Classroom y herramientas de terceros se enfrentan al desafío de configurar sus cursos y listas en varias plataformas. Esto se puede hacer de forma manual, ya sea mediante cargas de archivos CSV o ingresando correos electrónicos de a uno. Sin embargo, con la API de Classroom, las herramientas de terceros pueden reducir las cargas de trabajo de los profesores, ya que se integran en el caso de uso más común de la API: la importación de listas.
La importación de listas permite que las plataformas de terceros recuperen los metadatos, los profesores y los estudiantes de un curso curso por curso con permisos de profesor o administrador. Los profesores pueden recuperar detalles de los cursos que dictan, mientras que los administradores tienen acceso a los detalles de todos los cursos de un dominio entero. Esta flexibilidad permite a los desarrolladores integrar sin problemas las listas de Classroom en su plataforma, tanto a nivel de un profesor individual como en todo un dominio, mediante el uso de credenciales de administrador.
Antes de profundizar en los detalles técnicos de cómo podría ser una integración de importación de listas, revisemos primero un flujo de trabajo de ejemplo:
En la aplicación de terceros, el profesor elige la opción para importar un curso de Classroom.
La aplicación de terceros llama al método
courses.lista través de la API de Classroom, que mostrará una respuesta JSON con todos los cursos del profesor.Desde la respuesta JSON, la aplicación de terceros muestra los títulos de los cursos del profesor para que puedan seleccionar uno. La solicitud deberá realizar un seguimiento de los ID del curso para continuar con el siguiente paso.
Con el ID del curso seleccionado, la aplicación de terceros llama a los métodos
students.listyteachers.list, y muestra todos los nombres en su sitio web para que los profesores los confirmen antes de la importación.Con los correos electrónicos que se muestran en los archivos JSON de respuesta
students.listyteachers.list, la aplicación de terceros invita a los usuarios a unirse al curso recién importado a su plataforma.
En cada uno de los métodos mencionados en el flujo de trabajo, puedes usar el Explorador de API para ver exactamente cómo se comporta cada método. También recomendamos las siguientes lecturas previas antes de finalizar esta guía:
Getting Started
Antes de implementar los detalles de la importación de listas de Classroom, deberás determinar qué información de usuarios y cursos deberás recuperar mediante la API. Puedes ver qué metadatos del curso están disponibles en la documentación de referencia, pero se pueden resumir algunos de los campos obligatorios o comunes que se necesitan a continuación:
| Campo | Usa |
|---|---|
| id | Obligatorio para las solicitudes a la API que recuperan a estudiantes o profesores |
| name | Se recomienda para facilitar su uso, es decir, para mostrarse en tu sitio web |
| ownerId | Es obligatorio cuando se importan datos de todo el dominio para identificar correctamente al profesor principal de un curso. |
La información de este curso se recupera en el paso courses.list del flujo de trabajo anterior. En esta solicitud, puedes especificar ciertos parámetros de solicitud. Si bien ninguno es obligatorio para este método, algunos parámetros recomendados son los siguientes:
| Parámetro | Usa |
|---|---|
| courseState | Si no se especifica, la API mostrará cursos de los seis estados de curso. Recomendamos especificar ACTIVE para recuperar los cursos que estén usando los profesores actualmente. |
| pageSize | Para los profesores que importan sus propios cursos, recomendamos especificar un pageSize pequeño (menos de 10) para disminuir el tiempo de respuesta de la llamada a la API. |
| pageToken | Es obligatorio si usas solicitudes paginadas. |
| teacherId | Se recomienda porque los administradores de dominio suelen impartir cursos. Si no se especifica un valor, la solicitud mostrará cursos para profesores de todo el dominio. |
| campos | Se recomienda reducir el tiempo de respuesta de la llamada a la API. |
Con los IDs de cursos recuperados anteriormente, tu aplicación ahora puede recuperar la lista de estudiantes y profesores adjuntos de esos cursos. Este ID del curso es el único parámetro de consulta obligatorio para teachers.list y students.list, pero también puedes considerar especificar los parámetros pageSize y fields para disminuir el tiempo de respuesta de tus llamadas a la API.
Todos los campos disponibles para los recursos de estudiantes y profesores se pueden encontrar en la documentación correspondiente. Los dos campos necesarios que se usan con mayor frecuencia y que suelen ser obligatorios se encuentran en el campo profile: profile.name y profile.emailAddress.
| Campo | Usa |
|---|---|
| profile.name | Se recomienda para facilitar su uso, es decir, para mostrarse en tu sitio web |
| profile.emailAddress | Obligatorio para aplicaciones que buscan identificar de forma única a los estudiantes |
Para recuperar y usar cualquiera de los detalles de los cursos o listas de Classroom, tu aplicación deberá solicitar autorización a los usuarios. Existen tres (3) alcances obligatorios para implementar este flujo de trabajo:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Proporciona acceso de solo lectura a los cursos de Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Proporciona acceso de solo lectura a las listas de los cursos de Google Classroom (profesores y alumnos)
- https://www.googleapis.com/auth/classroom.profile.emails
- Proporciona acceso de lectura a la propiedad de correo electrónico de los profesores y los alumnos.
Sincroniza listas con notificaciones de Pub/Sub
A medida que avanza el año escolar, las listas pueden cambiar a medida que los estudiantes abandonan o agregan cursos. Agregar notificaciones de Pub/Sub te permitirá mantener tu aplicación de terceros sincronizada con las listas de Classroom. Para recibir notificaciones, configura un tema de Google Cloud Pub/Sub y, luego, registra el tema con la API de Classroom. Este registro es una solicitud para que Classroom envíe datos del feed determinado a un tema determinado. Este feed activará los eventos para volver a sincronizarse con la lista de Classroom de un profesor.
El uso de notificaciones push requerirá un alcance adicional, que no es necesario enviar para verificación:
- https://www.googleapis.com/auth/classroom.push-notifications
- Permite que tu app se registre para recibir cualquier actividad de notificación push
Para obtener más detalles sobre cómo integrar las notificaciones push de Classroom, consulta nuestra guía para administrar las notificaciones push.