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 utilisant le API Classroom pour recevoir 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 endroit où les notifications sont envoyées.
Un flux est un type de notifications qu'une application tierce peut vous abonner. Par exemple, "Modifications de la liste des participants au cours 1234".
Un enregistrement est une instruction adressée à l'API Classroom afin qu'elle fournisse notifications d'un flux donné 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 reçoit uniquement des notifications sur les ressources que vous peuvent afficher les identifiants que vous fournissez lors de la création d'un enregistrement. Pour C'est le cas, par exemple, si l'utilisateur révoque l'autorisation d'accès à votre application les notifications ne sont plus transmises.

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 accompagné d'un flux de modification des listes d'élèves, qui présente des notifications lorsque des élèves et des enseignants rejoignent ou quittent des cours dans ce de ce cours.
Chaque cours est associé à un flux Modifications des devoirs pour le cours, qui expose des notifications lorsqu'un devoir ou un devoir est envoyé par un élève 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 sur 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 activer la facturation pour votre projet dans la console 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éer un abonnement dans le cloud Pub/Sub, pour indiquer à Cloud à Pub/Sub comment distribuer vos notifications.
Enfin, avant de vous inscrire aux notifications push, vous devez accorder le Compte de service de notifications push ([email protected]) l'autorisation de publier sur votre sujet.

REMARQUE : Si vous autorisez le compte de service Notifications push à publier des messages sur votre sujet Cloud Pub/Sub, les utilisateurs autorisés à envoyer des requêtes à partir de votre projet de console de développement pourront déterminer qu'il existe et s'y abonner pour recevoir des notifications. De nombreuses applications stockent les ID client OAuth sur le client. afin que les utilisateurs finaux puissent envoyer des demandes depuis votre console développeur. projet. Si vous êtes dans cette situation et que vous craignez que des utilisateurs finaux envoient des notifications indésirables à votre sujet Cloud Pub/Sub ou connaître les noms des sujets Pub/Sub que vous utilisez pour les notifications push, nous vous conseillons l'inscription aux notifications push à partir d'un autre projet de la Developer Console.

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 cloud fourni Le sujet Pub/Sub peut être atteint par le compte de service des notifications push. 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é par un jeton d'autorisation. Ce Le jeton d'authentification doit inclure le champ d'application des notifications push (https://www.googleapis.com/auth/classroom.push-notifications) et tout autre élément des champs d’application sont nécessaires pour afficher les données sur les notifications envoyées.

Pour les flux de modification des listes d'élèves, cela correspond au champ d'application des listes d'élèves ou (idéalement) 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 que les "élèves" versions du cours le champ d'application du travail 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 le application, les notifications cessent. Notez qu'actuellement, la délégation au niveau du domaine n'est 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 qui a été modifiée. Pour notifications concernant les modifications apportées à la liste d'élèves. Il s'agit de courses.students ou courses.teachers Pour les modifications de devoirs, il s'agit de l'une des options suivantes : courses.courseWork ou courses.courseWork.studentSubmissions.
Identifiants de la ressource qui a été modifiée, dans un mappage. 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 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 illustre un exemple de notification:

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

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