Les enseignants qui utilisent à la fois Classroom et des outils tiers sont confrontés au défi de configurer leurs cours et leurs listes d'élèves sur plusieurs plates-formes. Cela peut être fait manuellement, soit en important des fichiers CSV, soit en saisissant les adresses e-mail une par une. Toutefois, grâce à l'API Classroom, les outils tiers peuvent réduire la charge de travail des enseignants en s'intégrant au cas d'utilisation le plus courant de l'API : l'importation de listes.
L'importation des listes d'élèves permet aux plates-formes tierces de récupérer les métadonnées, les enseignants et les élèves d'un cours, cours par cours, avec des autorisations d'enseignant ou d'administrateur. Les enseignants peuvent récupérer des informations sur les cours qu'ils dispensent, tandis que les administrateurs ont accès aux informations de tous les cours d'un domaine entier. Cette flexibilité permet aux développeurs d'intégrer facilement les listes de cours Classroom à leur plate-forme, que ce soit au niveau d'un enseignant ou d'un domaine entier, en utilisant les identifiants d'administrateur.
Avant d'examiner les détails techniques d'une intégration d'importation de listes, passons en revue un exemple de workflow :
Dans l'application tierce, un enseignant choisit l'option permettant d'importer un cours Classroom.
L'application tierce appelle la méthode
courses.listvia l'API Classroom, qui renvoie une réponse JSON avec tous les cours de l'enseignant.À partir de la réponse JSON, l'application tierce affiche les titres des cours de l'enseignant pour qu'il puisse en sélectionner un. L'application devra suivre les ID de cours pour passer à l'étape suivante.
Avec l'ID de cours sélectionné, l'application tierce appelle les méthodes
students.listetteachers.list, et affiche tous les noms sur son site Web pour que les enseignants puissent confirmer l'importation.À l'aide des adresses e-mail renvoyées dans les fichiers JSON de réponse
students.listetteachers.list, l'application tierce invite les utilisateurs à rejoindre le cours nouvellement importé sur sa plate-forme.
Pour chacune des méthodes mentionnées dans le workflow, vous pouvez utiliser l'explorateur d'API afin de voir exactement comment chaque méthode se comporte. Nous vous recommandons également de lire les articles suivants avant de terminer ce guide :
Premiers pas
Avant d'implémenter les spécificités de l'importation de votre liste de cours Classroom, vous devez déterminer les informations sur les cours et les utilisateurs que vous devrez récupérer via l'API. Vous pouvez consulter les métadonnées de cours disponibles dans la documentation de référence. Toutefois, vous trouverez ci-dessous un récapitulatif de certains champs obligatoires ou courants :
| Champ | Utiliser |
|---|---|
| id | Obligatoire pour les requêtes API permettant de récupérer des élèves ou des enseignants |
| nom | Recommandé pour la facilité d'utilisation par l'utilisateur, c'est-à-dire l'affichage sur votre site Web |
| ownerId | Obligatoire lors de l'importation au niveau du domaine pour identifier correctement l'enseignant principal d'un cours |
Ces informations sur le cours sont récupérées à l'étape courses.list du workflow ci-dessus. Dans cette requête, vous pouvez spécifier certains paramètres. Bien qu'aucun paramètre ne soit obligatoire pour cette méthode, voici quelques paramètres recommandés :
| Paramètre | Utiliser |
|---|---|
| courseState | Si aucune valeur n'est spécifiée, l'API renvoie les cours des six états de cours. Nous vous recommandons de spécifier ACTIVE pour récupérer les cours que les enseignants utilisent actuellement. |
| pageSize | Pour les enseignants qui importent leurs propres cours, nous recommandons de spécifier une petite taille de page (moins de 10) afin de réduire le temps de réponse de l'appel d'API. |
| pageToken | Obligatoire si vous utilisez des requêtes paginées. |
| teacherId | Recommandé, car les administrateurs de domaine donnent souvent des cours. Si aucune valeur n'est spécifiée, la requête renvoie les cours des enseignants de l'ensemble du domaine. |
| champs | Recommandé pour réduire le temps de réponse de l'appel d'API. |
À l'aide des ID de cours récupérés précédemment, votre application peut désormais récupérer la liste des élèves et des co-enseignants pour ce cours ou ces cours. Cet ID de cours est le seul paramètre de requête requis pour teachers.list et students.list, mais vous pouvez également envisager de spécifier les paramètres pageSize et fields pour réduire le temps de réponse de vos appels d'API.
Tous les champs disponibles pour les ressources student (élève) et teacher (enseignant) sont disponibles dans leur documentation respective. Les deux champs les plus couramment utilisés et généralement obligatoires se trouvent dans le champ profile : profile.name et profile.emailAddress.
| Champ | Utiliser |
|---|---|
| profile.name | Recommandé pour la facilité d'utilisation par l'utilisateur, c'est-à-dire l'affichage sur votre site Web |
| profile.emailAddress | Obligatoire pour les applications qui cherchent à identifier les élèves de manière unique |
Pour récupérer et utiliser ces informations sur les cours ou les listes à partir de Classroom, votre application devra demander l'autorisation aux utilisateurs. Trois (3) scopes sont requis pour implémenter ce workflow :
- https://www.googleapis.com/auth/classroom.courses.readonly
- Fournit un accès en lecture seule aux cours Google Classroom.
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Fournit un accès en lecture seule aux listes d'élèves des cours Google Classroom (enseignants et élèves)
- https://www.googleapis.com/auth/classroom.profile.emails
- Fournit un accès en lecture à la propriété email des enseignants et des élèves
Synchroniser les listes avec les notifications Pub/Sub
Au cours de l'année scolaire, les listes peuvent changer à mesure que les élèves abandonnent ou ajoutent des cours. L'ajout de notifications Pub/Sub vous permettra de synchroniser votre application tierce avec les listes de cours Classroom. Pour recevoir des notifications, vous devez configurer un sujet Google Cloud Pub/Sub, puis l'enregistrer auprès de l'API Classroom. Cette inscription est une demande d'envoi de données depuis le flux indiqué vers le thème indiqué. Ce flux servira de déclencheur d'événements pour la resynchronisation avec la liste des élèves d'un enseignant dans Classroom.
L'utilisation des notifications push nécessitera un champ d'application supplémentaire, qui n'a pas besoin d'être soumis à validation :
- https://www.googleapis.com/auth/classroom.push-notifications
- Permet à votre application de s'inscrire à toute activité de notification push
Pour en savoir plus sur l'intégration aux notifications push Classroom, consultez notre guide de gestion des notifications push.