Notifications push dans l'API Classroom

Vous pouvez utiliser les méthodes de la Registrations collection pour recevoir des notifications lorsque des données sont modifiées dans Classroom.

Cet article fournit une présentation conceptuelle ainsi que des instructions simples pour commencer à recevoir des notifications push.

Présentation des notifications push Classroom

La fonctionnalité de notifications push de l'API Classroom permet aux applications qui utilisent l'API Classroom de s'abonner aux notifications lorsque des données sont modifiées dans Classroom. Les notifications sont envoyées à un Cloud Pub/Sub sujet, généralement quelques minutes après la modification.

Pour recevoir des notifications push, vous devez configurer un sujet Cloud Pub/Sub et fournir le nom de ce sujet lorsque vous créez un enregistrement pour le flux de notifications approprié.

Vous trouverez ci-dessous les définitions des concepts clés utilisés dans cette documentation :

  • Une destination est un emplacement où les notifications sont envoyées.
  • Un flux est un type de notifications auquel une application tierce peut s'abonner. Par exemple, "modifications de la liste des élèves pour le cours 1234".
  • Un enregistrement est une instruction envoyée à l'API Classroom pour qu'elle envoie des notifications d'un flux particulier à une destination.

Une fois que vous avez créé un enregistrement pour un flux, le sujet Cloud Pub/Sub de cet enregistrement reçoit les notifications de ce flux jusqu'à son expiration. Votre enregistrement dure une semaine, mais vous pouvez le prolonger à tout moment avant son expiration en envoyant une requête identique à registrations.create().

Votre sujet Cloud Pub/Sub ne reçoit que les notifications concernant les ressources que vous pouvez afficher avec les identifiants que vous fournissez lors de la création d'un enregistrement. Par exemple, si l'utilisateur révoque l'autorisation de votre application ou est supprimé en tant qu'enseignant, les notifications ne sont plus envoyées.

Types de flux

L'API Classroom propose trois types de flux :

  • Chaque domaine dispose d'un flux modifications de la liste des élèves pour le domaine, qui expose les notifications lorsque des élèves et des enseignants rejoignent et quittent des cours dans ce domaine.
  • Chaque cours dispose d'un flux modifications de la liste des élèves pour le cours, qui expose les notifications lorsque des élèves et des enseignants rejoignent et quittent des cours dans ce cours.
  • Chaque cours dispose d'un flux modifications des devoirs pour le cours, qui expose les notifications lorsque des devoirs ou des devoirs rendus par les élèves sont créés ou modifiés dans ce cours.

Configurer un sujet Cloud Pub/Sub

Les notifications sont envoyées aux sujets Cloud Pub/Sub. Depuis Cloud Pub/Sub, vous pouvez recevoir des notifications sur un webhook ou en interrogeant un point de terminaison d'abonnement.

Pour configurer un sujet Cloud Pub/Sub, procédez comme suit :

  1. Assurez-vous de respecter les prérequis de Cloud Pub/Sub.
  2. Configurez un client Cloud Pub/Sub.
  3. Consultez les tarifs de Cloud Pub/Sub, et activez la facturation pour votre projet dans la console pour les développeurs.

  4. Créez un sujet Cloud Pub/Sub dans la console pour les développeurs (le plus simple), via l'outil de ligne de commande (pour une utilisation programmatique simple) ou à l'aide de l'API Cloud Pub/Sub. Notez que Cloud Pub/Sub n'autorise qu'un nombre limité de sujets. Par conséquent, l'utilisation d'un seul sujet pour recevoir toutes vos notifications vous permet d'éviter les problèmes de scaling si votre application devient populaire.

  5. Créez un abonnement dans Cloud Pub/Sub pour indiquer à Cloud Pub/Sub comment envoyer vos notifications.

  6. Enfin, avant de vous inscrire aux notifications push, vous devez accorder au compte de service Notifications push (classroom-notifications@system.gserviceaccount.com) l'autorisation de publier sur votre sujet.

Inscrire votre application pour recevoir des notifications

Une fois que vous disposez d'un sujet sur lequel le compte de service Notifications push de l'API Classroom peut publier, vous pouvez vous inscrire pour recevoir des notifications à l'aide de la méthode registrations.create(). La méthode registrations.create() valide que le compte de service Notifications push peut accéder au sujet Cloud Pub/Sub fourni. La méthode échoue si le compte de service Notifications push ne peut pas accéder au sujet, par exemple si le sujet n'existe pas ou si vous ne lui avez pas accordé l'autorisation de publication sur ce sujet.

Autorisation

Comme tous les appels à l'API Classroom, les appels à registrations.create() doivent être autorisés avec un jeton d'autorisation. Ce jeton d'authentification doit inclure le champ d'application Notifications push (https://www.googleapis.com/auth/classroom.push-notifications) et tous les champs d'application requis pour afficher les données sur lesquelles les notifications sont envoyées.

  • Pour les flux de modifications de la liste des élèves, cela signifie le champ d'application Listes des élèves ou (idéalement) sa variante en lecture seule (https://www.googleapis.com/auth/classroom.rosters.readonly ou https://www.googleapis.com/auth/classroom.rosters).
  • Pour les flux de modifications des devoirs, cela signifie les versions "élèves" du champ d'application Devoirs ou (idéalement) sa variante en lecture seule (https://www.googleapis.com/auth/classroom.coursework.students.readonly ou https://www.googleapis.com/auth/classroom.coursework.students).

Pour que les notifications soient envoyées, l'application doit conserver une autorisation OAuth de l'utilisateur autorisé avec les champs d'application requis. Si l'utilisateur déconnecte l'application, les notifications cessent. Notez que pour le moment, la délégation d'autorité à l'échelle du domaine n'est pas prise en charge à cette fin. Si vous tentez de vous inscrire pour recevoir des notifications en utilisant uniquement l'autorité déléguée à l'échelle du domaine, vous recevrez une erreur @MissingGrant.

Recevoir des notifications

Les notifications sont encodées au format JSON et contiennent les éléments suivants :

  • Nom de la collection contenant la ressource modifiée. Pour les notifications concernant les modifications de la liste des élèves, il s'agit de courses.students ou courses.teachers. Pour les modifications des devoirs, il s'agit de courses.courseWork ou courses.courseWork.studentSubmissions.
  • Identifiants de la ressource modifiée, dans une carte. Cette carte est conçue pour correspondre aux arguments de la méthode get de la ressource appropriée. Pour les notifications concernant les modifications de la liste des élèves, les champs courseId et userId seront renseignés et pourront être envoyés sans modification à courses.students.get() ou courses.teachers.get(). De même, les modifications apportées à la collection courses.courseWork auront des champs courseId et id qui pourront être envoyés sans modification à courses.courseWork.get() et les modifications apportées à la collection courses.courseWork.studentSubmissions auront des champs courseId, courseWorkId, et id qui pourront être envoyés sans modification à courses.courseWork.studentSubmissions.get().

L'extrait de code suivant illustre un exemple de notification :

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

Les notifications comportent également un attribut de message registrationId, qui contient l' identifiant de l'enregistrement à l'origine de la notification. Cet identifiant peut être utilisé avec registrations.delete() pour se désinscrire des notifications.