Notificaciones push en la API de Classroom

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

Este artículo proporciona una descripción general conceptual junto con instrucciones simples sobre cómo comenzar a recibir notificaciones automáticas.

Descripción general de las notificaciones automáticas de Classroom

La función de notificaciones automáticas de la API de Classroom permite que las aplicaciones que usan la API de Classroom se suscriban para recibir notificaciones cuando los datos cambian en Classroom. Las notificaciones se envían a un tema de Cloud Pub/Sub , por lo general, unos minutos después del cambio.

Para recibir notificaciones automáticas, debe configurar un tema de Cloud Pub/Sub y proporcionar el nombre de ese tema cuando crea un registro para la fuente de notificaciones adecuada.

A continuación se encuentran las definiciones de los conceptos clave utilizados en esta documentación:

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

Una vez que crea 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 caduque haciendo una solicitud idéntica a registrations.create() .

Su tema de Cloud Pub/Sub solo recibe notificaciones sobre los recursos que puede ver con las credenciales que proporciona al crear un registro. Por ejemplo, si el usuario revoca el permiso de su aplicación o es eliminado como maestro, las notificaciones se entregarán por más tiempo.

tipos de alimentacion

La API de Classroom actualmente ofrece tres tipos de feed:

  • Cada dominio tiene una lista de cambios para el feed de dominio , que expone notificaciones cuando los estudiantes y profesores se unen y abandonan los cursos en ese dominio.
  • Cada curso tiene una lista de cambios para el feed del curso , que expone notificaciones cuando los estudiantes y los profesores se unen y abandonan los cursos en ese curso.
  • Cada curso tiene cambios en el trabajo del curso para la fuente del curso, que expone notificaciones cuando se crea o modifica cualquier trabajo del curso o objetos de envío de estudiantes en ese curso.

Configurar un tema de Cloud Pub/Sub

Las notificaciones se envían a los temas de Cloud Pub/Sub. Desde Cloud Pub/Sub, puede recibir notificaciones en un enlace web o sondeando un punto final de suscripción.

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

  1. Asegúrese de cumplir con los requisitos previos de Cloud Pub/Sub .
  2. Configura un cliente de Cloud Pub/Sub .
  3. Revise los precios de Cloud Pub/Sub y habilite la facturación para su proyecto de Developer Console.
  4. Cree un tema de Cloud Pub/Sub en Developer Console (lo más fácil), a través de la herramienta de línea de comandos (para un uso programático simple) o mediante la API de Cloud Pub/Sub . Tenga en cuenta que Cloud Pub/Sub solo permite una cantidad limitada de temas , por lo que usar un tema para recibir todas sus notificaciones garantiza que no tenga problemas de escalado si su aplicación se vuelve popular.

  5. Cree una suscripción en Cloud Pub/Sub para decirle a Cloud Pub/Sub cómo entregar sus notificaciones.

  6. Finalmente, antes de registrarse para las notificaciones automáticas, debe otorgar permiso a la cuenta del servicio de notificaciones automáticas ( classroom-notifications@system.gserviceaccount.com ) para publicar en su tema.

NOTA: Si otorga permiso a la cuenta del servicio de notificaciones push para publicar en su tema de Cloud Pub/Sub, los usuarios que pueden realizar solicitudes desde su proyecto de Developer Console podrán determinar que existe y registrarse para recibir notificaciones. Muchas aplicaciones almacenan ID de cliente de OAuth en el lado del cliente, por lo que los usuarios finales pueden realizar solicitudes desde su proyecto de Developer Console. Si esto se aplica a usted y le preocupa que los usuarios finales envíen notificaciones no deseadas a su tema de Cloud Pub/Sub o conozcan los nombres de los temas de Cloud Pub/Sub que usa para las notificaciones automáticas, debería considerar registrarse para recibir notificaciones automáticas desde un proyecto diferente de Developer Console.

Registre su aplicación para notificaciones

Una vez que tenga un tema en el que la cuenta del servicio de notificaciones push de la API de Classroom pueda publicar, puede registrarse para recibir notificaciones mediante el método registrations.create() . El método registrations.create() valida que la cuenta del servicio de notificaciones push pueda acceder al tema de Cloud Pub/Sub proporcionado. El método falla si la cuenta del servicio de notificaciones push no puede acceder al tema; por ejemplo, si el tema no existe o no le ha otorgado permiso de publicación sobre ese tema.

Autorización

Como 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 alcances necesarios para ver los datos sobre qué notificaciones se envían.

  • Para los feeds de cambio de lista, esto significa el alcance de las listas o (idealmente) su variante de solo lectura ( https://www.googleapis.com/auth/classroom.rosters.readonly o https://www.googleapis.com/auth/classroom.rosters ).
  • Para las fuentes de cambio de trabajo del curso, esto significa las versiones de "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 conservar una concesión de OAuth del usuario autorizado con los alcances requeridos. Si el usuario desconecta la aplicación, las notificaciones cesan. Tenga en cuenta que, actualmente, no se admite la delegación de autoridad en todo el dominio para este fin. Si intenta registrarse para recibir notificaciones utilizando solo la autoridad delegada en todo el dominio, recibirá un error `@MissingGrant.

Recibir notificaciones

Las notificaciones están codificadas con JSON y contienen:

  • El nombre de la colección que contiene el recurso que cambió. Para notificaciones sobre cambios en la lista, esto es courses.students o courses.teachers . Para cambios en el trabajo del curso, este 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 notificaciones sobre cambios en la lista, los campos de ID de courseId y ID de userId se completarán y se pueden enviar sin modificar a Courses.students.get() o Courses.teachers.get() . De manera similar, los cambios en la colección de courseId tendrán campos de id y de Id de curso que se pueden enviar sin modificar a Courses.CourseWork.get() y los cambios en la colección de courseId tendrán campos de id y de courseWorkId que se pueden enviado sin modificar a Courses.courseWork.studentSubmissions.get() .

El siguiente fragmento de código 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 del registro que provocó la notificación, que se puede usar con registrations.delete() para cancelar el registro de las notificaciones.