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 fournit une présentation conceptuelle et des instructions simples pour commencer à recevoir des notifications push.

Présentation des notifications push de Classroom

La fonctionnalité de notifications push de l'API Classroom permet aux applications utilisant cette API de s'abonner aux notifications en cas de modification de donné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 indiquer son nom lorsque vous créez un enregistrement du flux de notifications approprié.

Voici les définitions des concepts clés utilisés dans cette documentation:

Une destination est un emplacement d'envoi des notifications.
Un flux est un type de notifications auxquelles une application tierce peut s'abonner. Par exemple, "révolutions du cours 1234".
Une inscription est une instruction destinée à l'API Classroom qui permet de transmettre les notifications d'un flux spécifique à 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 de notifications que pour 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 s'il est retiré en tant qu'enseignant, les notifications sont plus longues.

Types de flux

L'API Classroom propose actuellement trois types de flux:

Chaque domaine dispose d'un flux de modifications continues pour le domaine, qui envoie des notifications lorsque les élèves et les enseignants rejoignent et quittent les cours de ce domaine.
Chaque cours comporte un flux de modifications apportées au cours, qui envoie des notifications lorsque les élèves et les enseignants rejoignent et quittent les cours de ce cours.
Chaque cours est associé à un flux de modification des devoirs qui présente des notifications en cas de création ou de modification d'objets de travail ou de devoirs d'étudiants 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 point d'ancrage Web ou interroger 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 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 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. Ainsi, 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 distribuer 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) la publication sur votre sujet.

REMARQUE: Si vous autorisez le compte de service des notifications push à publier dans votre sujet Cloud Pub/Sub, les utilisateurs pouvant envoyer des requêtes à partir de votre projet de console développeur pourront le vérifier et s'inscrire pour recevoir des notifications. De nombreuses applications stockent les ID client OAuth côté client. Les utilisateurs finaux peuvent donc peut-être envoyer des requêtes à partir de votre projet de la console développeur. Si vous êtes dans cette situation et si 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 devez envisager de vous inscrire pour recevoir des notifications push provenant d'un autre projet de la Developer Console.

Enregistrer votre application pour les notifications

Une fois que vous avez un sujet dans lequel le compte de service de notifications push de l'API Classroom peut publier, vous pouvez vous enregistrer pour recevoir des notifications à l'aide de la méthode registrations.create(). La méthode registrations.create() vérifie que le compte de service push notifications peut accéder au sujet Cloud Pub/Sub fourni. 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).

Autorisation

Comme pour 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 les champs d'application requis pour afficher les données concernant les notifications envoyées.

Pour les flux avec modification de la liste d'élèves, cela signifie le champ d'application 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).
Pour les flux de changement de devoir du cours, cela signifie les versions "étudiants" du champ d'application du cours 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 cesseront. Notez que la délégation au niveau du domaine n'est actuellement pas compatible à cette fin. Si vous tentez d'enregistrer des notifications en utilisant uniquement une autorité déléguée au niveau du domaine, vous recevrez un message d'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 sur les modifications de liste d'élèves, il s'agit de courses.students ou courses.teachers. Pour les modifications de cours, 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 faire correspondre les arguments à la méthode get de la ressource appropriée. Pour les notifications de modification de la liste d'élèves, les champs courseId et userId sont renseignés et peuvent être envoyés non modifiés dans courses.students.get() ou courses.teachers.get(). De même, les modifications apportées à la collection courses.courseWork comportent des champs courseId et id pouvant être envoyés non modifiés à courses.course.get.get.change.get.get.get

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

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

Les notifications disposent également d'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.