Présentation

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 d'élèves.

L'importation de 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 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, au niveau d'un enseignant ou d'un domaine entier, à l'aide d'identifiants d'administrateur.

Les administrateurs de domaine peuvent utiliser des outils tiers en tant qu'enseignants de leurs propres cours. Il est nécessaire de gérer avec soin la différence entre les autorisations d'administrateur de domaine et d'enseignant lors de la récupération des détails d'un cours via l'API.

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 :

1. Dans l'application tierce, un enseignant choisit l'option permettant d'importer un cours Classroom Course.

2. L'application tierce appelle la méthode courses.list via l'API Classroom, qui renvoie une réponse JSON avec tous les cours de l'enseignant.

3. À partir de la réponse JSON, l'application tierce affiche les titres des cours de l'enseignant afin qu'il puisse en sélectionner un. L'application devra suivre les ID des cours pour passer à l'étape suivante.

4. Avec l'ID de cours sélectionné, l'application tierce appelle les méthodes students.list et teachers.list, puis affiche tous les noms sur son site Web pour que les enseignants confirment l'importation.

5. À l'aide des adresses e-mail renvoyées dans les réponses JSON students.list et teachers.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'API Explorer pour voir exactement comment chaque méthode se comporte. Nous vous recommandons également de lire les articles suivants avant de terminer ce guide :

1. Gérer les cours avec l'API Classroom
2. Gérer les élèves et les enseignants

En plus du schéma de workflow ci-dessous, consultez l'exemple en direct d'ActivelyLearn pour mieux comprendre ce type d'intégration.

Premiers pas

Avant d'implémenter les spécificités de l'importation de votre liste d'élèves 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, mais certains champs obligatoires ou courants peuvent être résumés ci-dessous :

Champ	Utiliser
id	Obligatoire pour les requêtes API récupérant des élèves ou des enseignants
nom	Recommandé pour faciliter l'utilisation par l'utilisateur, par exemple en l'affichant 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 ne soit obligatoire pour cette méthode, voici quelques paramètres recommandés :

Paramètre	Utiliser
courseState	Si ce paramètre n'est pas spécifié, 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 vous recommandons de spécifier une petite valeur (inférieure à 10) pour pageSize 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 enseignent 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 pour ce ou ces cours. Cet ID de cours est le seul paramètre de requête obligatoire 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 des élèves et des enseignants se trouvent dans leur documentation respective. Les deux champs les plus couramment utilisés et généralement obligatoires se trouvent dans le profile champ: profile.name et profile.emailAddress.

Champ	Utiliser
profile.name	Recommandé pour faciliter l'utilisation par l'utilisateur, par exemple en l'affichant 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 d'élèves à partir de Classroom, votre application devra demander l'autorisation aux utilisateurs. Trois (3) niveaux d'accès 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é e-mail des enseignants et des élèves

Étant donné que l'un de ces niveaux d'accès est considéré comme sensible, votre application devra suivre une procédure de validation.

Synchroniser les listes d'élèves avec les notifications Pub/Sub

Au cours 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 permettra de synchroniser votre application tierce avec les listes d'élèves Classroom. Pour recevoir des notifications, configurez un sujet Google Cloud Pub/Sub, puis enregistrez-le auprès de l'API Classroom. Cet enregistrement est une demande adressée à Classroom pour qu'il envoie des données du flux donné au sujet donné. Ce flux sera le déclencheur d'événement pour la resynchronisation avec la liste d'élèves Classroom d'un enseignant.

Selon le cas d'utilisation de votre application, vous pouvez vous abonner aux notifications par cours ou par domaine.

L'utilisation de notifications push nécessitera un niveau d'accès 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 Gérer les notifications push.