Los complementos de Google Classroom ya están en fase de disponibilidad general para desarrolladores. Consulta la documentación sobre complementos para obtener más información.

Se usó la API de Cloud Translation para traducir esta página.

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 para recibir notificaciones cuando cambian los datos 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 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 notificaciones.
Un feed es un tipo de notificaciones al que se puede suscribir una aplicación de terceros. Por ejemplo, "Cambios en la lista del curso 1234".
Un registro es una instrucción para que la API de Classroom envíe 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 del feed hasta que vence. El registro dura una semana, pero puedes extenderlo en cualquier momento antes de que venza haciendo una solicitud idéntica a registrations.create().

Tu tema de Cloud Pub/Sub solo recibe notificaciones sobre los 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, ya no se enviarán notificaciones.

Tipos de feeds

La API de Classroom ofrece tres tipos de feeds:

Cada dominio tiene un feed de cambios en la lista del dominio, que expone notificaciones cuando los estudiantes y los profesores se unen a los cursos de ese dominio 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 a los cursos y los abandonan.
Cada curso tiene un feed de cambios en el trabajo del curso, que expone notificaciones cuando se crean o modifican objetos de trabajo del curso o de entrega de estudiantes en ese curso.

Configurar 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:

Asegúrate de cumplir con los requisitos previos de Cloud Pub/Sub.
Configura un cliente de Cloud Pub/Sub.
Revisa los precios de Cloud Pub/Sub y habilita la facturación para tu proyecto de Developer Console.
Crea un tema de Cloud Pub/Sub en la consola para desarrolladores (la más sencilla), 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 garantiza que no tendrás problemas de escalamiento si tu aplicación se vuelve popular.
Crea una suscripción en Cloud Pub/Sub para indicarle a Cloud Pub/Sub cómo entregar tus notificaciones.
Por último, antes de registrarte para recibir notificaciones push, debes otorgar permiso a la cuenta de servicio de notificaciones push (classroom-notifications@system.gserviceaccount.com) para publicar en tu tema.

Registra tu aplicación para recibir notificaciones

Una vez que tengas un tema al que pueda publicar la cuenta de servicio de las notificaciones push de la API de Classroom, puedes 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 desde 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

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 alcance de las notificaciones push (https://www.googleapis.com/auth/classroom.push-notifications) y los alcances que sean necesarios para ver los datos sobre qué notificaciones se envían.

En el caso de los feeds de cambios de la lista, 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 trabajos 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 conservar un otorgamiento de OAuth del usuario autorizado con los permisos requeridos. Si el usuario desconecta la aplicación, se detendrán las notificaciones. Ten en cuenta que, actualmente, no se admite la delegación de autoridad en todo el dominio para este propósito. Si intentas registrarte para recibir notificaciones usando solo la autoridad delegada en todo el dominio, recibirás un error @MissingGrant.

Recibir notificaciones

Las notificaciones están codificadas 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 la lista, puede ser courses.students o courses.teachers. Para los cambios en el trabajo del curso, este valor es courses.courseWork o courses.courseWork.studentSubmissions.
Son los 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. En el caso de las notificaciones sobre cambios en la lista, se propagarán los campos courseId y userId, y se podrán enviar sin modificaciones a courses.students.get() o courses.teachers.get(). Del mismo modo, los cambios en la colección courses.courseWork tendrán los 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 los 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.