Les modules complémentaires Google Classroom sont désormais disponibles pour tous les développeurs. Pour en savoir plus, consultez la documentation sur les modules complémentaires.

Cette page a été traduite par l'API Cloud Translation.

Notifications push dans l'API Classroom

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

Cet article fournit un aperçu conceptuel 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 sujet Cloud Pub/Sub, 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 endroit où les notifications sont envoyées.
Un flux est un type de notifications auxquelles 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 des notifications de ce flux jusqu'à son expiration. Votre inscription dure une semaine, mais vous pouvez la 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 membres du domaine qui affiche des notifications lorsque des élèves et des enseignants rejoignent ou quittent des cours dans ce domaine.
Chaque cours dispose d'un flux Modifications apportées à la liste des élèves du cours, qui affiche des notifications lorsque des élèves et des enseignants rejoignent ou quittent des cours.
Chaque cours dispose d'un flux Modifications des devoirs pour le cours, qui affiche des 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, vous devez procéder comme suit :

Assurez-vous de remplir les conditions préalables de Cloud Pub/Sub.
Configurez un client Cloud Pub/Sub.
Consultez les tarifs de Cloud Pub/Sub et activez la facturation pour votre projet dans la console Developer.
Créez un sujet Cloud Pub/Sub dans la console Developer (la méthode la plus simple), à l'aide de 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 mise à l'échelle si votre application devient populaire.
Créez un abonnement dans Cloud Pub/Sub pour indiquer à Cloud Pub/Sub comment envoyer vos notifications.
Enfin, avant de vous inscrire aux notifications push, vous devez accorder au compte de service des notifications push (classroom-notifications@system.gserviceaccount.com) l'autorisation de publier sur votre sujet.

Remarque : Si vous autorisez le compte de service Notifications push à publier sur votre sujet Cloud Pub/Sub, les utilisateurs qui peuvent envoyer des requêtes depuis votre projet de la console Developer pourront déterminer qu'il existe et s'y abonner pour recevoir des notifications. De nombreuses applications stockent les ID client OAuth côté client. Les utilisateurs finaux peuvent donc être en mesure d'envoyer des requêtes depuis votre projet de la console de développement. Si cela vous concerne et que vous craignez que les utilisateurs finaux envoient des notifications indésirables à votre sujet Cloud Pub/Sub ou connaissent les noms des sujets Cloud Pub/Sub que vous utilisez pour les notifications push, vous devriez envisager de vous inscrire aux notifications push à partir d'un autre projet de la console Developer.

Enregistrer votre application pour les notifications

Une fois que vous disposez d'un sujet sur lequel le compte de service de notifications push de l'API Classroom peut publier, vous pouvez vous inscrire aux notifications à l'aide de la méthode registrations.create(). La méthode registrations.create() valide que le compte de service de notifications push peut accéder au sujet Cloud Pub/Sub fourni. La méthode échoue si le compte de service de 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 "Notifications push" (https://www.googleapis.com/auth/classroom.push-notifications) et tous les champs requis pour afficher les données sur les notifications envoyées.

Pour les flux de modification de la liste, cela signifie que le champ "Rosters" ou (idéalement) sa variante en lecture seule (https://www.googleapis.com/auth/classroom.rosters.readonly ou https://www.googleapis.com/auth/classroom.rosters) est requis.
Pour les flux de modifications des devoirs, cela signifie les versions "élèves" du champ d'application des 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 niveaux d'accès requis. Si l'utilisateur déconnecte l'application, les notifications cessent. Notez que la délégation d'autorité à l'échelle du domaine n'est actuellement pas prise en charge à cette fin. Si vous essayez de vous inscrire aux 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 qui a été modifiée. Pour les notifications concernant les modifications apportées à la liste, la valeur est courses.students ou courses.teachers. Pour les modifications apportées aux devoirs, la valeur est courses.courseWork ou courses.courseWork.studentSubmissions.
Identifiants de la ressource qui a été modifiée, dans une carte. Cette carte est conçue pour faire correspondre les arguments à la méthode get de la ressource appropriée. Pour les notifications concernant les modifications apportées à 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 présente 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. Il peut être utilisé avec registrations.delete() pour se désinscrire des notifications.