Notificaciones push en la API de Classroom

Puedes usar los métodos en la 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 usen La API de Classroom permite suscribirse para recibir 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 Cloud Pub/Sub tema y proporciona el nombre de ese tema cuando crees un registro para el feed apropiado de notificaciones.

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 de lista para el curso 1234”.
  • Un registro es una instrucción que se le da a la API de Classroom para realizar la entrega notificaciones de un feed específico a un destino.

Una vez que crees un registro para un feed, el registro será Cloud Pub/Sub tema recibe notificaciones de ese feed hasta que caduque. Tu registro que dura una semana, pero puede extenderlo en cualquier momento antes de que caduque haciendo 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. Para ejemplo, si el usuario revoca el permiso de tu aplicación o se quita como el profesor, las notificaciones ya no se entregan.

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 unan y abandonen los cursos en ese dominio.
  • 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 el trabajo del curso que expone notificaciones cuando un trabajo del curso o un objeto de entrega de los estudiantes se que creaste o modificaste 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 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 para recibir todas las notificaciones, te aseguras de no tener problemas de escalamiento si tu aplicación se vuelve popular.

  5. Cómo crear una suscripción en Cloud Pub/Sub, para indicarle a Cloud Pub/Sub para enviar notificaciones.

  6. Por último, antes de registrarte en Notificaciones push, debes otorgar permiso a la cuenta de servicio de Notificaciones push (classroom-notifications@system.gserviceaccount.com) para publicar 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 conocer los nombres de los Los temas de Pub/Sub que usas para las notificaciones push, deberías considerar cómo registrarte para recibir notificaciones push desde otro proyecto de Play Console.

Registra tu aplicación para recibir notificaciones

Una vez que tengas un tema que la cuenta de servicio de notificaciones push de la API de Classroom puedes publicar, puedes registrarte para recibir notificaciones usando el registrations.create() . El método registrations.create() valida que el servicio de Cloud Se puede acceder al tema de Pub/Sub con 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 en ese tema.

Autorización

Como todas las llamadas a la API de Classroom, las llamadas a registrations.create() deben autorizado con un token de autorización. Esta el token de autenticación debe incluir el alcance de notificaciones push (https://www.googleapis.com/auth/classroom.push-notifications) y lo que sea se requieren para ver los datos sobre qué notificaciones se envían.

  • En el caso de los feeds de cambios de listas, esto significa que el alcance de listas o (idealmente) sus 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 trabajos del curso, esto significa que los “alumnos” más recientes del curso alcance de trabajo 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, actualmente, la delegación de todo el dominio de no se admite la autoridad para este fin. Si intentas registrarte para recibir notificaciones con solo la autoridad delegada en 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 en el listado, es courses.students o courses.teachers. Para los cambios en el trabajo del curso, esto 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 adecuado. 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.