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 sencillas 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 a notificaciones cuando cambien los datos en Classroom. Las notificaciones se entregan a un tema de Cloud Pub/Sub, por lo general, en 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 incluyen las definiciones de los conceptos clave que se usan 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 de estudiantes del curso 1234".
  • Un registro es una instrucción para la API de Classroom para entregar 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 venza. Tu registro dura una semana, pero puedes extenderlo en cualquier momento antes de que venza realizando 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 lo quita como profesor, las notificaciones dejarán de entregarse.

Tipos de feeds

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

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

Configura un tema de Cloud Pub/Sub

Las notificaciones se entregan a temas de Cloud Pub/Sub. Desde Cloud Pub/Sub, puedes recibir notificaciones en un webhook o sondeando 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 Play Console.

  4. Crea un tema de Cloud Pub/Sub en la consola de desarrollador (la forma más fácil), a través de la herramienta de línea de comandos (para un uso programático sencillo) 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 tengas 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 en Notificaciones push, debes otorgarle permiso a la cuenta de servicio de Notificaciones push (classroom-notifications@system.gserviceaccount.com) para que publique en tu tema.

NOTA: Si otorgas a la cuenta de servicio de notificaciones push permiso para publicar en tu tema de Cloud Pub/Sub, los usuarios que puedan realizar solicitudes desde tu proyecto de la Consola de Play podrán determinar que existe y registrarse para recibir notificaciones en él. Muchas aplicaciones almacenan IDs de cliente de OAuth en el cliente, por lo que los usuarios finales podrían realizar solicitudes desde tu proyecto de Developer Console. Si este es tu caso y te preocupa que los usuarios finales envíen notificaciones no deseadas a tu tema de Cloud Pub/Sub o conozcan los nombres de los temas de Cloud Pub/Sub que usas para las notificaciones push, te recomendamos que te registres para recibir notificaciones push desde otro proyecto de la Consola de Play 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 con 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 para ese tema.

Autorización

Al igual que todas las llamadas a la API de Classroom, las llamadas a registrations.create() deben estar autorizadas 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 cualquier permiso que sea necesario para ver los datos sobre qué notificaciones se envían.

  • En el caso de los feeds de cambios de lista, esto significa el permiso de Rosters o, de preferencia, 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 significa las versiones para "estudiantes" 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, dejan de recibir 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 con solo la autoridad delegada en todo el dominio, recibirás un error @MissingGrant.

Recibe notificaciones

Las notificaciones se codifican con JSON y contienen lo siguiente:

  • Es el nombre de la colección que contiene el recurso que cambió. Para las notificaciones sobre cambios en el listado, es courses.students o courses.teachers. Para los cambios en el trabajo del curso, es courses.courseWork o courses.courseWork.studentSubmissions.
  • Son 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 correspondiente. Para las notificaciones sobre cambios en el listado de estudiantes, se propagarán los campos courseId y userId, y se pueden enviar sin modificaciones a courses.students.get() o courses.teachers.get(). Del mismo modo, los cambios en la colección courses.courseWork tendrán campos courseId y id que se pueden enviar sin modificaciones a courses.courseWork.get(), y los cambios en la colección courses.courseWork.studentSubmissions tendrán campos courseId, courseWorkId y id que se pueden enviar sin modificaciones a courses.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 anular el registro de las notificaciones.