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 les données changent dans Classroom.

Cet article présente une vue d'ensemble conceptuelle et 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 à des notifications lorsque des données changent dans Classroom. Les notifications sont envoyées à un sujet Cloud Pub/Sub, généralement dans les minutes qui suivent la modification.

Pour recevoir des notifications push, vous devez configurer un sujet Cloud Pub/Sub et indiquer son nom lorsque vous créez une inscription 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ù des 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 participants au cours 1234".
Un enregistrement est une instruction envoyée à l'API Classroom pour qu'elle envoie des notifications à partir d'un flux particulier vers une destination.

Une fois que vous avez créé une inscription pour un flux, le sujet Cloud Pub/Sub de cette inscription reçoit des 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 des notifications que sur 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 actuellement trois types de flux:

Chaque domaine dispose d'un flux Modifications de la liste pour le domaine, qui affiche des notifications lorsque des élèves et des enseignants rejoignent et quittent des cours de ce domaine.
Chaque cours est associé à un flux de modifications des listes d'élèves, qui affiche des notifications lorsque des élèves et des enseignants rejoignent ou quittent des cours dans ce cours.
Chaque cours dispose d'un flux Modifications des devoirs pour le cours, qui affiche des notifications lorsqu'un devoir ou un objet de devoir d'élève est créé ou modifié 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 via un webhook ou en interrogeant un point de terminaison d'abonnement.

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

Assurez-vous de remplir les conditions préalables à 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 du développeur.
Créez un sujet Cloud Pub/Sub dans la console du développeur (méthode la 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, utiliser 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 autoriser le compte de service Notifications push (classroom-notifications@system.gserviceaccount.com) à publier dans votre sujet.

REMARQUE: Si vous autorisez le compte de service de notifications push à publier sur votre sujet Cloud Pub/Sub, les utilisateurs autorisés à envoyer des requêtes à partir de votre projet de la Developer Console pourront déterminer qu'il existe et s'inscrire pour recevoir des notifications. De nombreuses applications stockent des ID client OAuth côté client. Les utilisateurs finaux peuvent donc être en mesure d'effectuer des requêtes à partir de votre projet de console de développement. Si vous vous trouvez dans cette situation 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 pour les notifications push à partir d'un autre projet de la console du développeur.

Enregistrer votre application pour recevoir des notifications

Une fois que vous avez 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() vérifie que le sujet Cloud Pub/Sub fourni peut être atteint par le compte de service de notifications push. La méthode échoue si le compte de service de notifications push ne peut pas accéder au sujet, par exemple s'il 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 des notifications push (https://www.googleapis.com/auth/classroom.push-notifications) et tous les champs d'application requis pour afficher les données sur les notifications envoyées.

Pour les flux de modifications de la composition, il s'agit de la portée "Équipes" ou (dans l'idéal) de 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 modification des devoirs de cours, cela signifie les versions "étudiants" du champ d'application du devoir 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 arrête de se connecter à l'application, les notifications cessent. Notez que la délégation d'autorité au niveau du domaine n'est actuellement pas prise en charge à cette fin. Si vous essayez de vous inscrire pour recevoir des notifications à l'aide de l'autorité déléguée au niveau du domaine uniquement, une erreur @MissingGrant s'affiche.

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 d'équipe, la valeur est courses.students ou courses.teachers. Pour les modifications de devoirs de cours, il s'agit de courses.courseWork ou courses.courseWork.studentSubmissions.
Identifiants de la ressource qui a été modifiée, dans un mappage. Ce mappage est conçu 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 participants, 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 comporteront 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 comporteront 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, contenant l'identifiant de l'enregistrement à l'origine de la notification, qui peut être utilisé avec registrations.delete() pour se désinscrire des notifications.