Notificaciones push en la API de Classroom

Puedes usar los métodos de la colección Registrations para recibir notificaciones cuando cambien los datos en Classroom.

En este artículo, se proporciona una descripción general conceptual junto con instrucciones simples sobre cómo comenzar a recibir notificaciones push.

Descripción general de las notificaciones push de Classroom

La función de notificaciones push de la API de Classroom permite que las aplicaciones que usan esta API se suscriban para recibir notificaciones cuando cambien los datos en Classroom. Las notificaciones se entregan a un tema de Cloud Pub/Sub, por lo general, a unos minutos después del cambio.

Para recibir notificaciones push, debes configurar un tema de Cloud Pub/Sub y proporcionar el nombre de ese tema cuando crees un registro para el feed de notificaciones adecuado.

A continuación, se muestran las definiciones de los conceptos clave usados en esta documentación:

  • Un destino es un lugar al que se envían las notificaciones.
  • Un feed es un tipo de notificaciones al que se puede suscribir una aplicación de terceros. Por ejemplo, "cambios en la lista para el curso 1234".
  • Un registro es una instrucción para la API de Classroom que debe enviar notificaciones de un feed en particular a un destino.

Una vez que creas un registro para un feed, el tema de Cloud Pub/Sub de ese registro recibe notificaciones de ese feed hasta que vence. Tu registro dura una semana, pero puedes extenderlo en cualquier momento antes de que venza si envías una solicitud idéntica a registrations.create().

El tema de Cloud Pub/Sub solo recibe notificaciones sobre los recursos que puedes ver con las credenciales que proporcionas al momento de crear un registro. Por ejemplo, si el usuario revoca el permiso de tu aplicación o se lo quita como profesor, las notificaciones se entregarán durante más tiempo.

Tipos de feeds

Actualmente, la API de Classroom ofrece tres tipos de feed:

  • Cada dominio tiene un feed de cambios en la lista para el dominio, que expone notificaciones cuando los estudiantes y profesores se unen a los cursos y los abandonan en ese dominio.
  • Cada curso tiene un feed de cambios en la lista del curso, que expone notificaciones cuando los estudiantes y profesores se unen a los cursos y los abandonan.
  • Cada curso tiene un feed de cambios de trabajo del curso para el curso, que expone notificaciones cuando se crea o modifica algún trabajo del curso o objetos de entrega de los estudiantes en ese curso.

Configura un tema de Cloud Pub/Sub

Las notificaciones se entregan a los temas de Cloud Pub/Sub. Desde Cloud Pub/Sub, puedes recibir notificaciones en un webhook o sondear un extremo de suscripción.

Para configurar un tema de Cloud Pub/Sub, debes hacer lo siguiente:

  1. Asegúrate de cumplir con los requisitos previos de Cloud Pub/Sub.
  2. Configura un cliente de Cloud Pub/Sub.
  3. Revisa los precios de Cloud Pub/Sub y habilita la facturación para tu proyecto de Developer Console.

  4. Crea un tema de Cloud Pub/Sub en Play Console (de la forma más fácil), a través de la herramienta de línea de comandos (para un uso programático simple) o con la API de Cloud Pub/Sub. Ten en cuenta que Cloud Pub/Sub solo permite una cantidad limitada de temas, por lo que usar un tema para recibir todas tus notificaciones te garantiza que no se produzcan problemas de escalamiento si tu aplicación se vuelve popular.

  5. Crea una suscripción en Cloud Pub/Sub para indicarle a Cloud Pub/Sub cómo entregar tus notificaciones.

  6. Por último, antes de registrarte para las notificaciones push, debes otorgar el permiso de la cuenta de servicio de notificaciones push (classroom-notifications@system.gserviceaccount.com) para publicar en tu tema.

NOTA: Si otorgas permiso a la cuenta de servicio de notificaciones push para publicar en tu tema de Cloud Pub/Sub, los usuarios que pueden hacer solicitudes desde tu proyecto de Developer Console podrán determinar que existe y registrarse para recibir notificaciones sobre él. Muchas aplicaciones almacenan los IDs de cliente de OAuth en el lado del cliente, por lo que los usuarios finales pueden realizar solicitudes desde tu proyecto de Play Console. Si esto se aplica a ti y te preocupa que los usuarios finales envíen notificaciones no deseadas a tu tema de Cloud Pub/Sub o que conozcas los nombres de los temas de Cloud Pub/Sub que usas para las notificaciones push, deberías considerar registrarte para las notificaciones push de un proyecto diferente de Play Console.

Registra tu aplicación para recibir notificaciones

Cuando tengas un tema en el que pueda publicar la cuenta de servicio de notificaciones push de la API de Classroom, podrás registrarte para recibir notificaciones con el método registrations.create(). El método registrations.create() valida que se pueda acceder al tema de Cloud Pub/Sub proporcionado mediante la cuenta de servicio de notificaciones push. El método falla si la cuenta de servicio de notificaciones push no puede acceder al tema; por ejemplo, si el tema no existe o no le otorgaste permiso de publicación sobre ese tema.

Autorización

Al igual que todas las llamadas a la API de Classroom, las llamadas a registrations.create() deben autorizarse con un token de autorización. Este token de autenticación debe incluir el permiso de notificaciones push (https://www.googleapis.com/auth/classroom.push-notifications) y los permisos necesarios para ver los datos sobre qué notificaciones se envían.

  • Para los feeds de cambios de listas, esto significa el alcance de Rosters o (idealmente) su variante de solo lectura (https://www.googleapis.com/auth/classroom.rosters.readonly o https://www.googleapis.com/auth/classroom.rosters).
  • En el caso de los feeds de cambios de trabajo del curso, esto se refiere a las versiones para "alumnos" del alcance del trabajo del curso o (idealmente) su variante de solo lectura (https://www.googleapis.com/auth/classroom.coursework.students.readonly o https://www.googleapis.com/auth/classroom.coursework.students).

Para que se entreguen las notificaciones, la aplicación debe retener un otorgamiento de OAuth del usuario autorizado con los alcances requeridos. Si el usuario desconecta la aplicación, cesan las notificaciones. Ten en cuenta que, por el momento, la delegación de autoridad de todo el dominio no es compatible con este propósito. Si intentas registrarte para recibir notificaciones solo con la autoridad delegada de todo el dominio, recibirás un error @MissingGrant.

Recibe notificaciones

Las notificaciones están codificadas con JSON y contienen lo siguiente:

  • El nombre de la colección que contiene el recurso que cambió. Para las notificaciones sobre cambios de listas, el valor es courses.students o courses.teachers. Para los cambios en el trabajo del curso, es courses.courseWork o courses.courseWork.studentSubmissions.
  • Identificadores del recurso que cambió, en un mapa. Este mapa está diseñado para hacer coincidir los argumentos con el método get del recurso adecuado. Para las notificaciones sobre cambios de listas, los campos courseId y userId se propagarán, y se pueden enviar sin modificar a courses.students.get() o a courses.teachers.get(). Del mismo modo, los cambios en la colección courses.courseWork tendrá los campos courseId y id que se pueden enviar sin modificar a courses.courseWork.get().courseIdidcourseWorkIdcourses.courseWork.studentSubmissions.get()

En el siguiente fragmento de código, se muestra una notificación de ejemplo:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

Las notificaciones también tienen un atributo de mensaje registrationId, que contiene el identificador del registro que causó la notificación, que se puede usar con registrations.delete() para cancelar el registro en las notificaciones.