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 offre une présentation conceptuelle et explique comment commencer à recevoir des notifications push.

Présentation des notifications push Classroom

La fonctionnalité de notifications push de l'API Classroom permet aux applications qui l'utilisent de s'abonner aux 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 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 l'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 pour le cours 1234".
Un enregistrement est une instruction destinée à l'API Classroom pour envoyer des notifications à partir d'un flux particulier vers 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 enregistrement dure une semaine, mais vous pouvez le prolonger à tout moment avant qu'il n'expire en envoyant une demande 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 actuellement trois types de flux:

Chaque domaine dispose d'un flux de modifications pour le domaine, qui envoie des notifications lorsque les élèves et les enseignants rejoignent ou quittent les cours de ce domaine.
Chaque cours est associé à un flux de modifications pour le cours, qui envoie des notifications lorsque les élèves et les enseignants rejoignent ou quittent un cours.
Chaque cours est associé à un flux de modifications des devoirs, qui envoie des notifications lorsque des devoirs ou des objets soumis 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. À partir de Cloud Pub/Sub, vous pouvez recevoir des notifications via un hook Web 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 développeur.
Créez un sujet Cloud Pub/Sub dans la console 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, l'utilisation d'un seul sujet pour recevoir toutes vos notifications vous évite de rencontrer des problèmes de scaling si votre application devient populaire.
Créez un abonnement dans Cloud Pub/Sub pour indiquer à Cloud Pub/Sub comment diffuser vos notifications.
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 dans votre sujet.

REMARQUE: Si vous accordez au compte de service Notifications push l'autorisation de publier sur votre sujet Cloud Pub/Sub, les utilisateurs autorisés à effectuer des requêtes depuis votre projet Play Console pourront vérifier qu'il existe et s'y inscrire pour recevoir des notifications. De nombreuses applications stockent les ID client OAuth côté client. Les utilisateurs finaux peuvent donc envoyer des requêtes à partir de votre projet dans la console développeur. Si cela vous concerne et que vous craignez que les utilisateurs finaux envoient des notifications indésirables à votre sujet Cloud Pub/Sub ou que vous connaissiez les noms des sujets Cloud Pub/Sub que vous utilisez pour les notifications push, envisagez de vous inscrire aux notifications push à partir d'un autre projet de la Play Console.

Enregistrer votre application pour recevoir des notifications

Une fois que vous disposez d'un sujet sur lequel le compte de service des 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 est accessible par le compte de service des notifications push. La méthode échoue si le compte de service de notifications push ne peut pas atteindre le 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 à l'aide d'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 concernant les notifications envoyées.

Pour les flux de modification des listes d'élèves, il s'agit du champ d'application des listes d'élèves ou (idéalement) 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 modifications des devoirs, il s'agit des versions "élèves" du champ d'application des devoirs ou (idéalement) de 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 transmises, 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 d'être envoyées. Notez qu'actuellement, la délégation d'autorité au niveau du domaine n'est pas acceptée à cette fin. Si vous tentez de vous inscrire aux notifications en utilisant uniquement une autorité déléguée au niveau 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 liste d'élèves, il s'agit de courses.students ou de courses.teachers. Pour les modifications de devoirs, il s'agit de courses.courseWork ou de courses.courseWork.studentSubmissions.
Identifiants de la ressource modifiée, dans une carte. 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 d'élèves, les champs courseId et userId seront renseignés et pourront être envoyés tels quels à courses.students.get() ou courses.teachers.get(). De même, les modifications apportées à la collection courses.courseWork comporteront les champs courseId et id qui pourront être envoyés tels quels dans courses.courseWork.get()courseWorkIdcourses.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.