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 a través de cargas de CSV o ingresando los correos electrónicos uno por uno. Sin embargo, con la API de Classroom, las herramientas de terceros pueden reducir la carga de trabajo de los profesores integrándose con el caso de uso más común de la API: la importación de listas de estudiantes.
La importación de listas permite que las plataformas de terceros recuperen los metadatos, los profesores y los estudiantes de un curso por curso con permisos de profesor o administrador. Los profesores pueden recuperar detalles de los cursos que enseñan, mientras que los administradores tienen acceso a los detalles de todos los cursos de todo el dominio. Esta flexibilidad permite a los desarrolladores integrar sin problemas las listas de Classroom en su plataforma, ya sea a nivel de un profesor individual o en todo un dominio, con credenciales de administrador.
Antes de analizar los detalles técnicos de cómo podría verse una integración de importación de listas, primero revisemos un flujo de trabajo de ejemplo:
En la aplicación de terceros, los profesores eligen 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.En la respuesta JSON, la aplicación de terceros muestra los títulos de los cursos del profesor para que seleccione uno. La aplicación deberá hacer un seguimiento de los IDs de los cursos para continuar con el siguiente paso.
Con el ID del curso seleccionado, la aplicación de terceros llama a los métodos
students.listyteachers.listy muestra todos los nombres en su sitio web para que los profesores los confirmen para la importación.Con los correos electrónicos que se muestran en los JSON de respuesta
students.listyteachers.list, la aplicación de terceros invita a los usuarios a unirse al curso importado recientemente en su plataforma.
Para 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 uno. También te recomendamos hacer las siguientes lecturas previas antes de finalizar esta guía:
Comenzar
Antes de implementar los detalles de la importación de la lista de Classroom, deberás determinar qué información del curso y del usuario deberás recuperar a través de la API. Puedes ver qué metadatos de cursos están disponibles en la documentación de referencia, pero algunos campos obligatorios o comunes se pueden resumir a continuación:
| Campo | Usar |
|---|---|
| id | Obligatorio para las solicitudes a la API que recuperan estudiantes o profesores |
| nombre | Se recomienda para facilitar el uso del usuario, es decir, para mostrarlo en tu sitio web. |
| ownerId | Obligatorio cuando se realiza la importación en todo el dominio para identificar correctamente al profesor principal de un curso |
Esta información del 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, estos son algunos parámetros recomendados:
| Parámetro | Usar |
|---|---|
| courseState | Si no se especifica, la API mostrará cursos de los seis estados de curso. Recomendamos especificar ACTIVE para recuperar los cursos que los profesores están usando actualmente. |
| pageSize | En el caso de los profesores que importan sus propios cursos, recomendamos especificar un valor pequeño (menos de 10) para pageSize para disminuir el tiempo de respuesta de la llamada a la API. |
| pageToken | Obligatorio si usas solicitudes paginadas. |
| teacherId | Se recomienda porque los administradores de dominios suelen dictar cursos. Si no se especifica, la solicitud mostrará cursos para profesores de todo el dominio. |
| campos | Se recomienda disminuir el tiempo de respuesta de la llamada a la API. |
Con los IDs de los cursos recuperados anteriormente, tu aplicación ahora puede recuperar la lista de estudiantes y profesores adjuntos de ese curso o cursos. Este ID del curso es el único parámetro de consulta requerido para teachers.list y students.list, pero, de manera similar, quizás desees 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 su documentación respectiva. Los dos campos necesarios que se usan con más frecuencia y, por lo general, se requieren, se encuentran en el campo profile: profile.name y profile.emailAddress.
| Campo | Usar |
|---|---|
| profile.name | Se recomienda para facilitar el uso del usuario, es decir, para mostrarlo en tu sitio web. |
| profile.emailAddress | Obligatorio para las aplicaciones que buscan identificar a los estudiantes de forma inequívoca |
Para recuperar y usar cualquiera de estos detalles de cursos o listas de Classroom, tu aplicación deberá solicitar la autorización de los usuarios. Se requieren tres (3) permisos 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 estudiantes de los cursos de Google Classroom (profesores y estudiantes).
- https://www.googleapis.com/auth/classroom.profile.emails
- Proporciona acceso de lectura a la propiedad correo electrónico de los profesores y los alumnos.
Cómo sincronizar listas de participantes 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. Si agregas notificaciones de Pub/Sub, podrás mantener tu aplicación de terceros sincronizada con las listas de Classroom. Para recibir notificaciones, configuras un tema de Google Cloud Pub/Sub y, luego, lo registras con la API de Classroom. Este registro es una solicitud para que Classroom envíe datos del feed determinado al tema determinado. Este feed será el activador del evento para volver a sincronizar con la lista de Classroom de un profesor.
El uso de notificaciones push requerirá un permiso adicional, que no es necesario enviar para su verificación:
- https://www.googleapis.com/auth/classroom.push-notifications
- Permite que tu app se registre para cualquier actividad de notificaciones push.
Para obtener más detalles sobre cómo realizar la integración con las notificaciones push de Classroom, consulta nuestra guía para administrar notificaciones push.