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 para 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 la API de Classroom 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, 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 creas un registro para el feed de notificaciones correspondiente.

A continuación, encontrará las definiciones de los conceptos clave que se usan en esta documentación:

  • Un destino es el lugar al que se envían las notificaciones.
  • Un feed es un tipo de notificaciones a las que se puede suscribir una aplicación de terceros. Por ejemplo, "cambios en la lista del curso 1234".
  • Un registro es una instrucción a la API de Classroom para entregar notificaciones desde un feed específico 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 realizas una solicitud idéntica a registrations.create().

Tu tema de Cloud Pub/Sub solo recibe notificaciones sobre recursos que puedes ver con las credenciales que proporcionas cuando creas un registro. Por ejemplo, si el usuario revoca el permiso de tu aplicación o se quita como profesor, las notificaciones se entregan por más tiempo.

Tipos de feeds

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

  • Cada dominio tiene un feed de cambios para el dominio, que expone notificaciones cuando los estudiantes y los profesores se unen y abandonan los cursos de ese dominio.
  • Cada curso tiene un feed de cambios en la lista del curso, que expone notificaciones cuando los alumnos y los profesores se unen y abandonan los cursos de ese curso.
  • Cada curso tiene un feed de trabajos del curso por curso, que expone notificaciones cuando se crean o modifican objetos de trabajo o de entrega para estudiantes.

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 hook web 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 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 Developer Console (más fácil), a través de la herramienta de línea de comandos (para simplificar el uso programático) 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 asegura que no tendrás 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 las notificaciones.

  6. Por último, antes de registrarte para recibir notificaciones push, debes otorgar el permiso de la cuenta de servicio de notificaciones push (classroom-notifications@system.gserviceaccount.com) a fin de 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 puedan hacer solicitudes desde tu proyecto de Developer Console podrán determinar que existe y registrarse para recibir notificaciones. Muchas aplicaciones almacenan los ID de cliente de OAuth en el lado del cliente, por lo que es posible que los usuarios finales puedan hacer solicitudes desde tu proyecto de la Consola para programadores. Si esto se aplica a tu caso y te preocupa que los usuarios finales envíen notificaciones no deseadas a tu tema de Cloud Pub/Sub o sepan los nombres de los temas de Cloud Pub/Sub que usas para notificaciones push, deberías considerar registrarte en notificaciones push desde otro proyecto de Developer Console.

Registra tu aplicación para recibir notificaciones

Una vez que tengas un tema en el que la cuenta de servicio de notificaciones push de la API de Classroom pueda publicar, puedes registrarte para recibir notificaciones mediante el método registrations.create(). El método registrations.create() valida que la cuenta de servicio de notificaciones push pueda acceder al tema de Cloud Pub/Sub proporcionado. 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 si no le otorgaste permiso de publicación en 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 alcance de las notificaciones push (https://www.googleapis.com/auth/classroom.push-notifications) y los permisos necesarios para ver los datos sobre las notificaciones que se envían.

  • En el caso de los feeds de cambios de listas, esto significa el alcance de la lista 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 cambio de trabajo del curso, esto significa que las versiones de los 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 una concesión de OAuth del usuario autorizado con los alcances requeridos. Si el usuario desconecta la aplicación, las notificaciones cesan. Ten en cuenta que, por el momento, la delegación de autoridad de todo el dominio no es compatible con este fin. Si intentas registrarte para recibir notificaciones solo con la autoridad delegada de todo el dominio, recibirás un error “@MissingGrant”.

Recibe notificaciones

Las notificaciones se codifican con JSON y contienen lo siguiente:

  • El nombre de la colección que contiene el recurso que cambió. En el caso de las notificaciones sobre cambios en la lista, puede ser courses.students o courses.teachers. Para los cambios en el trabajo del curso, debe ser 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 recibir notificaciones sobre los cambios en la lista, se propagarán los campos courseId y userId, y se podrán enviar sin modificar a courses.students.get() o courses.teachers.get(). Del mismo modo, los cambios a la colección courses.courseWork tendrán los campos courseId y id que se pueden modificar sin modificar a courses.courseWork.get().

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

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

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