Les enseignants qui utilisent à la fois Classroom et des outils tiers doivent configurer leurs cours et leurs listes d'élèves sur plusieurs plates-formes. Vous pouvez le faire manuellement, soit en utilisant des importations CSV, soit en saisissant les adresses e-mail une par une. Toutefois, avec 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 la liste des élèves.
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 par cours avec des autorisations d'enseignant ou d'administrateur. Les enseignants peuvent récupérer les 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 classe Classroom sur leur plate-forme, que ce soit au niveau d'un enseignant individuel ou de l'ensemble d'un domaine à l'aide d'identifiants administrateur.
Avant de vous plonger dans les détails techniques d'une intégration d'importation de liste d'équipe, examinons d'abord 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 doit 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, puis affiche tous les noms sur son site Web pour que les enseignants confirment l'importation.À l'aide des e-mails renvoyés dans les fichiers JSON de réponse
students.listetteachers.list, l'application tierce invite les utilisateurs à rejoindre le cours nouvellement importé sur leur plate-forme.
Pour chacune des méthodes mentionnées dans le workflow, vous pouvez utiliser l'explorateur d'API pour 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 détails de l'importation de votre liste de cours Classroom, vous devez déterminer les informations sur le 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, mais certains champs obligatoires ou courants peuvent être résumés ci-dessous:
| Champ | Utiliser |
|---|---|
| id | Obligatoire pour les requêtes API qui récupèrent des élèves ou des enseignants |
| nom | Recommandé pour faciliter l'utilisation par l'utilisateur, c'est-à-dire pour l'afficher sur votre site Web |
| ownerId | Obligatoire lors de l'importation à l'échelle 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 de requête. 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 de chacun 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 vous recommandons de spécifier une valeur de pageSize faible (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 dispensent souvent des cours. Si ce paramètre n'est pas spécifié, 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 de ce 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 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 élève et enseignant se trouvent dans leur documentation respective. Les deux champs les plus couramment utilisés et généralement requis se trouvent dans le champ profile : profile.name et profile.emailAddress.
| Champ | Utiliser |
|---|---|
| profile.name | Recommandé pour faciliter l'utilisation par l'utilisateur, c'est-à-dire pour l'afficher sur votre site Web |
| profile.emailAddress | Obligatoire pour les applications qui cherchent à identifier de manière unique les élèves |
Pour récupérer et utiliser l'un de ces détails de cours ou de liste de participants à partir de Classroom, votre application doit demander l'autorisation des utilisateurs. Trois (3) champs d'application 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 effectifs des cours Google Classroom (enseignants et élèves)
- https://www.googleapis.com/auth/classroom.profile.emails
- Accorde un accès en lecture à la propriété adresse e-mail des enseignants et des élèves
Synchroniser les listes de diffusion avec les notifications Pub/Sub
Au fil de l'année scolaire, les listes peuvent changer à mesure que des élèves abandonnent ou ajoutent des cours. Ajouter des notifications Pub/Sub vous permettra de synchroniser votre application tierce avec les listes de classe. Pour recevoir des notifications, vous devez configurer un sujet Google Cloud Pub/Sub, puis l'enregistrer auprès de l'API Classroom. Cet enregistrement est une requête demandant à Classroom d'envoyer les données du flux donné au sujet donné. Ce flux déclenchera la resynchronisation avec la liste d'élèves Classroom d'un enseignant.
L'utilisation des notifications push nécessite un champ d'application supplémentaire, qui n'a pas besoin d'être envoyé pour 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 des notifications push Classroom, consultez notre guide de gestion des notifications push.