Ressources de l'API

Ce guide présente les principaux composants de l'API Google Classroom. L'API Google Classroom se compose de ressources et de services. Les ressources représentent des entités dans Google Classroom, comme un cours ou un devoir, et les services récupèrent et gèrent ces ressources. Certaines de ces entités possèdent des propriétés supplémentaires spécifiques à l'API en plus de celles qui existent dans Classroom. Voici les principaux types d'entités :

Entité	Représentation dans Classroom
Courses	Une classe, comme "M. Mathématiques, 4e période de M. Dupont".
Alias	ID alternatif pour un cours.
Invitations	Un moyen d'ajouter des utilisateurs à un cours.
Élèves	Un élève dans un cours.
Enseignants	Un enseignant d'un cours
Profils utilisateur	Un utilisateur de manière plus générale, en dehors du contexte d'élève ou d'enseignant.
CourseWork	Un devoir dans un cours.
StudentSubmissions	Travail d'un élève pour un devoir donné, comme des réponses ou des feuilles de calcul.
CourseWorkMaterials	Ressources pour les élèves d'un cours.
Annonces	Annonce destinée aux élèves d'un cours.
AddOnAttachment	Contenu ou activité d'un devoir ou d'un support qui s'affiche généralement sous la forme d'un iFrame intégré.
Thèmes	Regroupement visuel des devoirs et des supports de cours dans un cours.
Inscriptions	Instruction permettant d'envoyer des notifications à votre application en cas de modification des données, comme la liste des élèves d'un cours.

La plupart des ressources disposent de méthodes de service pour les opérations standards telles que la lecture, la mise à jour et la suppression des instances de la ressource. Certaines ressources disposent également de méthodes personnalisées pour d'autres opérations, comme la modification de la liste des élèves auxquels un devoir spécifique est attribué.

Pour obtenir des informations détaillées sur les ressources et les méthodes de l'API, consultez la documentation de référence de l'API Classroom.

Présentation des relations entre les ressources

• Le cours est l'objet de données de base dans Google Classroom.
• Les alias sont utilisés comme identifiants alternatifs pour Courses.
• Les invitations permettent d'inviter des profils utilisateur à devenir enseignants ou élèves dans un Course. Toutefois, les administrateurs de domaine Google Workspace for Education peuvent également ajouter des utilisateurs directement.
• Les enseignants créent des éléments du flux d'informations et les partagent avec les élèves de leurs cours. Les types d'éléments de flux possibles sont Coursework, CourseWorkMaterials et Announcements. Les CourseWork et CourseWorkMaterials peuvent être organisés visuellement en thèmes et peuvent contenir des AddOnAttachments. Les élèves envoient des StudentSubmissions pour leur CourseWork.
• Les développeurs peuvent créer des enregistrements pour recevoir des notifications lorsque certaines de ces données changent.

Google Classroom est disponible pour les domaines abonnés à Google Workspace for Education. Dans le contexte de Classroom, un domaine représente généralement un district scolaire. Vous pouvez créer un domaine de test Google Workspace for Education à des fins de développement. Vous contrôlez ainsi une instance de production de Classroom sans affecter les utilisateurs réels.

Cours et alias

Courses représente une classe, comme "M. Mathématiques de 4e période de M. Smith", ainsi que les enseignants qui y sont affectés, la liste des élèves et les métadonnées. Chaque cours est identifié par un ID unique attribué par le serveur. La ressource Course encapsule spécifiquement toutes les métadonnées du cours, telles que le nom, la description, le lieu et l'heure. Les listes de cours sont gérées à l'aide des ressources Student, Teacher et Invitation, ainsi que de leurs méthodes.

Aliases sont des identifiants alternatifs pour un cours, qui peuvent être associés à un cours et utilisés à la place de l'identifiant unique. Chaque alias existe dans un espace de noms qui limite les personnes autorisées à le créer et à l'afficher. Deux espaces de noms sont acceptés :

• Domaine : l'espace de noms de domaine est utile pour créer des alias auxquels tous les utilisateurs doivent avoir accès, mais qui ne sont spécifiques à aucun programme. Par exemple, les autres fiches d'un cours, telles que MATH 127 et COMSCI 127, doivent être créées dans l'espace de noms du domaine. Seuls les administrateurs de domaine peuvent créer des alias dans l'espace de noms du domaine, mais ils sont visibles par tous les utilisateurs d'un domaine.
• Projet de développeur : l'espace de noms du projet de développeur est utile pour gérer les alias spécifiques à une application. Par exemple, une application qui utilise d'autres identifiants pour les cours peut créer des alias pour mapper son identifiant aux cours Classroom. Les alias créés dans cet espace de noms sont associés à une console Google APIs spécifique. Tout utilisateur d'une application peut créer et afficher des alias dans l'espace de noms du projet de développement de cette application.

Pour en savoir plus sur la gestion des alias et des métadonnées de cours, consultez Gérer les cours.

Listes de cours et utilisateurs

Students et Teachers sont des mappages spécifiques entre un profil utilisateur et un cours, qui représentent le rôle de cet utilisateur dans le cours. Les désignations d'élève et d'enseignant ne sont pas globales : un utilisateur peut être désigné comme enseignant pour un cours et comme élève pour un autre. La désignation "élève" ou "enseignant" représente un ensemble d'autorisations pour un utilisateur donné dans un cours donné. Un cours peut comporter plusieurs enseignants ou aucun élève. Les enseignants et les élèves peuvent être ajoutés à un cours ou en être supprimés à tout moment.

Étudiants

Une ressource Student représente un utilisateur inscrit en tant qu'élève à un cours spécifique.

Les élèves sont autorisés à consulter les détails et les enseignants du cours.

les enseignants.

Une ressource Teacher représente un utilisateur qui enseigne un cours spécifique.

Les enseignants sont autorisés à afficher et à modifier les informations sur le cours, à afficher les enseignants et les élèves, et à gérer les enseignants et les élèves supplémentaires.

Invitations et les méthodes associées permettent d'ajouter facilement des élèves et des enseignants à des cours. Créer des invitations permet aux utilisateurs de choisir de rejoindre ou non un cours, plutôt que de les ajouter directement via les ressources pour les enseignants et les élèves.

UserProfiles représente un mappage vers le profil de domaine d'un utilisateur, tel qu'identifié par l'ID unique ou l'adresse e-mail de l'utilisateur renvoyé par l'API Directory. L'utilisateur actuel peut également faire référence à son propre ID à l'aide du raccourci "me".

Le service UserProfiles peut également être utilisé pour gérer et inviter des Guardians, qui sont des mappages entre un élève et un représentant légal. Dans Classroom, les représentants légaux ont accès à certaines informations sur les élèves, comme leurs devoirs.

Pour en savoir plus sur la gestion des listes, consultez Gérer les enseignants et les élèves.

Éléments du flux

Les éléments du flux sont les contenus publiés et partagés avec les membres d'un cours. Les développeurs et les enseignants peuvent créer trois types d'éléments de flux : Announcement, CourseWork et CourseWorkMaterial.

Les enseignants créent des Announcements en haut de la page "Flux" de l'interface utilisateur Classroom. Les enseignants créent des CourseWork et des CourseWorkMaterials en cliquant sur le bouton Créer de l'onglet "Travaux et devoirs". Les développeurs peuvent créer tous les types d'éléments de flux de manière programmatique à l'aide de l'API Classroom.

Voici quelques informations sur les éléments de flux :

• Tous les éléments du flux peuvent contenir des supports supplémentaires, tels que des fichiers Google Drive, des vidéos YouTube, des formulaires Google Forms, des liens hypertexte et des pièces jointes de modules complémentaires Classroom.
• Tous les éléments du flux peuvent être attribués à un sous-ensemble d'élèves du cours.
• Une CourseWork peut être notée ou non. Les enseignants peuvent modifier l'état de notation d'un devoir CourseWork à tout moment.
• Un élément du flux peut comporter plusieurs pièces jointes.
• Un élément de flux peut comporter des pièces jointes de différents types. Par exemple, un devoir CourseWork peut comporter simultanément des fichiers Google Drive, des vidéos YouTube et des pièces jointes de modules complémentaires Classroom.
• Un élément du flux peut comporter des pièces jointes supplémentaires provenant de plusieurs développeurs.
• Les développeurs peuvent obtenir et modifier les détails de n'importe quelle ressource d'élément de flux comportant l'une de leurs pièces jointes de module complémentaire.
• Les développeurs peuvent rendre, récupérer ou renvoyer le devoir d'un élève pour un devoir CourseWork qui inclut l'une de leurs pièces jointes de module complémentaire.
• Les développeurs ne peuvent finaliser les notes que pour les devoirs qu'ils ont créés et pour les devoirs individuels des élèves.

Éléments de flux copiés

Les enseignants peuvent copier un élément du flux en copiant un cours, en réutilisant un devoir ou en publiant un élément du flux dans plusieurs cours. Chaque nouvelle copie aura un identifiant distinct, ce qui peut être important si vous développez un module complémentaire Classroom. Consultez notre guide sur le contenu copié pour comprendre comment un module complémentaire peut gérer ces scénarios.

CourseWork et StudentSubmissions

Un élément CourseWork représente un devoir pour un groupe d'élèves dans un cours. Il s'agit du seul type d'élément du flux qui peut accepter un devoir envoyé par un élève. Une ressource CourseWork contient des informations telles que la description, la date limite, la note maximale et les métadonnées (comme la date de création).

Chaque ressource CourseWork décrit l'un des types de tâches suivants :

• Devoir que les élèves doivent effectuer en envoyant des feuilles de calcul ou d'autres pièces jointes.
• une question à réponse courte ou à choix multiples.

Les devoirs des élèves pour un élément CourseWork sont représentés par un StudentSubmission. Elle se compose d'une réponse et de métadonnées supplémentaires telles qu'un état et une note attribuée.

Le contenu d'un StudentSubmission dépend du type de l'élément CourseWork correspondant et peut inclure :

• Les feuilles de calcul et les pièces jointes envoyées pour un devoir, y compris leur titre, leur miniature et leur URL, ainsi que les identifiants pouvant être utilisés avec les API appropriées telles que Drive ou YouTube.
• Réponse à une question à réponse courte ou à choix multiples.

Pour en savoir plus sur la gestion des devoirs et des devoirs remis par les élèves, consultez Gérer les devoirs.

CoursWorkMaterials et Announcements

Comme CourseWork, CourseWorkMaterials représente le contenu attribué à un groupe d'élèves dans un cours. Chaque ressource comporte des informations telles qu'un titre et une description, ainsi que des documents complémentaires. Toutefois, contrairement à CourseWork, CourseWorkMaterials n'exige pas que les élèves envoient des artefacts. Par conséquent, il n'y a pas de date limite et StudentSubmissions n'existe pas pour CourseWorkMaterials. Les enseignants peuvent utiliser CourseWorkMaterials pour publier des suggestions de lecture, un programme ou le règlement de la classe.

Les éléments Announcements représentent également du contenu partagé avec un groupe d'élèves, mais ne comportent pas de détails comme un titre et ne peuvent pas être organisés par Topics comme CourseWork ou CourseWorkMaterials. Les enseignants peuvent les utiliser pour annoncer des rappels ou des informations à la classe.

Thèmes

Les Topics permettent d'organiser visuellement les CourseWork et les CourseWorkMaterials dans un cours. Par exemple, vous pouvez les utiliser pour regrouper les devoirs en "facultatifs" et "obligatoires", ou en "unité 1" et "unité 2".

Modules complémentaires Classroom

Un module complémentaire est une UI et un backend fournis par le développeur, généralement affichés dans un iframe. Les modules complémentaires apparaissent sous forme de pièces jointes dans un élément du flux. L'élément de flux peut être Announcements, CourseWork ou CourseWorkMaterials. Les pièces jointes des modules complémentaires sont représentées par un AddOnAttachment.

Les pièces jointes de modules complémentaires peuvent être une activité ou un contenu.

• Les pièces jointes d'activités exigent que les élèves effectuent et remettent un devoir individuel. Il peut s'agir de quiz, de dessins ou de jeux, par exemple. Une activité peut être notée (facultatif).
• Les pièces jointes de contenu ne nécessitent pas de devoir de la part des élèves. L'élève n'a pas besoin de rendre la pièce jointe et elle n'est pas notée. Il peut s'agir de photos, d'articles ou de vidéos, par exemple.

Pour en savoir plus, consultez les guides de développement des modules complémentaires.

Enregistrements

Les applications peuvent s'abonner aux notifications lorsque certaines données sont modifiées dans Google Classroom. Par exemple, lorsque la liste des élèves d'un cours est mise à jour. Registrations représente une instruction pour envoyer ces notifications à votre application.

Pour en savoir plus, consultez le guide sur les notifications push.