Los profesores que utilizan 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 la carga de archivos CSV o ingresando 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.
La importación de listas permite que las plataformas de terceros recuperen los metadatos, los profesores y los estudiantes de un curso de forma individual con permisos de profesor o administrador. Los profesores pueden recuperar detalles de los cursos que imparten, mientras que los administradores tienen acceso a los detalles de todos los cursos de un dominio completo. Esta flexibilidad permite a los desarrolladores incorporar sin problemas las listas de Classroom a su plataforma, ya sea a nivel de un profesor individual o en todo un dominio, con 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, primero revisemos un ejemplo de flujo de trabajo:
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 devolverá 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 este 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.list, y muestra todos los nombres en su sitio web para que los profesores confirmen la importación.Con los correos electrónicos que se muestran en los archivos JSON de respuesta de
students.listyteachers.list, la aplicación de terceros invita a los usuarios a unirse al curso recién importado en su plataforma.
Para cada uno de los métodos mencionados en el flujo de trabajo, puedes usar el Explorador de APIs para ver exactamente cómo se comporta cada método. También te recomendamos que leas los siguientes artículos antes de terminar esta guía:
Comenzar
Antes de implementar los detalles específicos de la importación de la lista de Classroom, deberás determinar qué información del curso y del usuario necesitarás recuperar a través de la API. Puedes ver qué metadatos del curso están disponibles en la documentación de referencia, pero algunos campos obligatorios o comunes necesarios se pueden resumir a continuación:
| Campo | Usar |
|---|---|
| id | Se requiere para las solicitudes a la API que recuperan estudiantes o profesores |
| nombre | Se recomienda para facilitar el uso al usuario, es decir, para mostrarlo en tu sitio web. |
| ownerId | Obligatorio cuando se importa a nivel del dominio para identificar correctamente al profesor principal de un curso |
La información del curso se recupera en el paso courses.list del flujo de trabajo anterior. En esta solicitud, puedes especificar ciertos parámetros. Si bien ninguno es obligatorio para este método, algunos parámetros recomendados son los siguientes:
| Parámetro | Usar |
|---|---|
| courseState | Si no se especifica, la API devolverá cursos de los seis estados de curso. Te recomendamos que especifiques ACTIVE para recuperar los cursos que los profesores usan actualmente. |
| pageSize | En el caso de 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 | Se requiere si usas solicitudes paginadas. |
| teacherId | Se recomienda porque los administradores de dominio suelen impartir cursos. Si no se especifica, la solicitud devolverá 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 o esos cursos. Este ID de curso es el único parámetro de consulta obligatorio para teachers.list y students.list, pero es posible que también desees especificar los parámetros pageSize y fields para reducir el tiempo de respuesta de tus llamadas a la API.
Todos los campos disponibles para los recursos de estudiantes y profesores se encuentran en su documentación respectiva. Los dos campos más comunes y que suelen ser obligatorios se encuentran en el campo profile: profile.name y profile.emailAddress.
| Campo | Usar |
|---|---|
| profile.name | Se recomienda para facilitar el uso al usuario, es decir, para mostrarlo en tu sitio web. |
| profile.emailAddress | Se requiere para las aplicaciones que buscan identificar a los estudiantes de forma única |
Para recuperar y usar cualquiera de estos detalles del curso o de la lista de Classroom, tu aplicación deberá solicitar autorización a 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 los cursos de Google Classroom (profesores y estudiantes).
- https://www.googleapis.com/auth/classroom.profile.emails
- Proporciona acceso de lectura a la propiedad email de profesores y estudiantes.
Sincroniza listas con notificaciones de Pub/Sub
A medida que avanza el año escolar, es posible que las listas cambien a medida que los estudiantes abandonen o agreguen cursos. Agregar notificaciones de Pub/Sub te permitirá mantener tu aplicación de terceros sincronizada con las listas de Classroom. Para recibir notificaciones, debes configurar un tema de Google Cloud Pub/Sub y, luego, registrarlo en 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 de eventos para volver a sincronizar la lista de Classroom de un profesor.
Para utilizar las notificaciones push, se requerirá un permiso adicional que no se debe enviar para su verificación:
- https://www.googleapis.com/auth/classroom.push-notifications
- Permite que tu app se registre para 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.