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. Cette opération peut être effectuée manuellement, en important un fichier CSV ou en saisissant des e-mails un par un. Cependant, avec l'API Classroom, les outils tiers peuvent réduire la charge de travail de leur enseignant en s'intégrant au cas d'utilisation le plus courant de l'API : l'importation de listes d'élèves.
L'importation de listes d'élèves permet à des plates-formes tierces de récupérer les métadonnées, les enseignants et les élèves d'un cours pour chaque cours, avec des autorisations d'enseignant ou d'administrateur. Les enseignants peuvent récupérer les détails des cours qu'ils enseignent, tandis que les administrateurs ont accès aux détails de tous les cours d'un domaine entier. Cette flexibilité permet aux développeurs d'intégrer facilement les listes d'élèves Classroom à leur plate-forme, aussi bien au niveau d'un enseignant individuel que sur l'ensemble d'un domaine, à l'aide d'identifiants d'administrateur.
Avant d'aborder les détails techniques de l'intégration d'une importation de listes d'élèves, examinons d'abord un exemple de workflow:
Dans l'application tierce, un enseignant choisit l'option d'importation d'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.Dans 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 garder une trace des ID de cours pour passer à l'étape suivante.
Avec l'ID de cours sélectionné, l'application tierce appelle les méthodes
students.listetteachers.listet affiche tous les noms sur son site Web pour que les enseignants puissent confirmer l'importation.En utilisant les adresses e-mail renvoyées dans les fichiers JSON de réponse
students.listetteachers.list, l'application tierce invite les utilisateurs à rejoindre le cours que vous venez d'importer sur leur plate-forme.
Pour chacune des méthodes mentionnées dans le workflow, vous pouvez utiliser APIs Explorer pour voir exactement comment chaque méthode se comporte. Nous vous recommandons également les lectures préalables suivantes avant de terminer ce guide:
Getting Started
Avant d'implémenter les spécificités de l'importation des listes d'élèves dans Classroom, vous devez déterminer les informations sur le cours et l'utilisateur que vous devez récupérer via l'API. Vous pouvez consulter les métadonnées du cours disponibles dans la documentation de référence, mais certains champs obligatoires ou courants nécessaires peuvent être résumés ci-dessous:
| Champ | Utilisation |
|---|---|
| id | Obligatoire pour les requêtes API récupérant des élèves ou des enseignants |
| name | Recommandé pour faciliter l'utilisation (affichage sur votre site Web) pour l'utilisateur |
| 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. Bien qu'aucun paramètre ne soit obligatoire pour cette méthode, voici quelques-uns des paramètres recommandés:
| Paramètres | Utilisation |
|---|---|
| courseState | Si elle n'est pas spécifiée, l'API affichera les cours des six états de cours. Nous vous recommandons de spécifier ACTIVE pour récupérer les cours actuellement utilisés par les enseignants. |
| pageSize | Pour les enseignants qui importent leurs propres cours, nous recommandons de spécifier une taille de page petite (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 aucune valeur n'est spécifiée, la requête affichera des cours pour les 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 maintenant récupérer la liste des élèves et des co-enseignants pour le cours ou les cours concernés. 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 élèves et enseignants se trouvent 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 | Utilisation |
|---|---|
| profile.name | Recommandé pour faciliter l'utilisation (affichage sur votre site Web) pour l'utilisateur |
| profile.emailAddress | Obligatoire pour les applications cherchant à identifier les élèves de façon unique. |
Pour récupérer et utiliser ces informations sur les cours ou les listes d'élèves depuis Classroom, votre application doit demander une autorisation aux utilisateurs. Trois (3) champs d'application sont obligatoires pour mettre en œuvre 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 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 d'élèves avec les notifications Pub/Sub
Au fur et à mesure de l'année scolaire, les listes d'élèves peuvent changer à mesure que les élèves abandonnent ou ajoutent des cours. L'ajout de notifications Pub/Sub vous permet de synchroniser votre application tierce avec les listes d'élèves Classroom. Pour recevoir des notifications, vous devez configurer un sujet Google Cloud Pub/Sub, puis l'enregistrer avec l'API Classroom. Cette inscription est une demande pour que Classroom envoie les données du flux en question au sujet concerné. Ce flux servira de déclencheur d'événements pour la resynchronisation avec la liste des é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 soumis pour validation:
- https://www.googleapis.com/auth/classroom.push-notifications
- Autorise votre appli à s'enregistrer pour toute activité de notification push
Pour savoir comment intégrer les notifications push de Classroom, consultez notre guide sur la gestion des notifications push.