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 propres à l'API en plus de celles qui existent dans Classroom. Les principaux types d'entités sont les suivants:

Entité Représentation dans Classroom
Courses Une classe, comme "M. Mathématiques, 4e heure, M. Smith".
Alias Autre identifiant d'un cours.
Invitations Méthode permettant d'ajouter des utilisateurs à un cours.
Élèves Élève dans un cours.
Enseignants Un enseignant dans un cours.
Profils utilisateur Utilisateur de manière générique, en dehors du contexte d'élève ou d'enseignant.
CourseWork Devoir dans un cours
StudentSubmissions Un élève travaille sur un devoir donné, comme des réponses ou des feuilles de calcul.
CourseWorkMaterials Matériel 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 cours, généralement affiché sous la forme d'un iframe intégré.
Thèmes Regroupement visuel des devoirs et des supports d'un cours.
Enregistrements Instruction d'envoi de notifications à votre application en cas de modification des données, comme la liste des élèves.

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 d'instances de la ressource. Certaines ressources disposent également de méthodes personnalisées pour d'autres opérations, telles que la modification de la liste des élèves auxquels une tâche particulière est attribuée.

Pour en savoir plus 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 de 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 une Course. Les utilisateurs peuvent également être ajoutés directement par les administrateurs de domaine Google Workspace for Education.
  • Les enseignants créent des éléments de flux et les partagent avec les élèves de leurs cours. Les types d'éléments de flux possibles sont Devoirs, Matériels de cours et Annonces. 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 qui sont 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. Cela vous permet de contrôler une instance de production de Classroom sans affecter les utilisateurs réels.

Cours et alias

Courses représente une classe, par exemple "M. "Maths de 4e période de M. Smith", ainsi que les enseignants, la liste des élèves et les métadonnées qui lui sont attribués. 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, l'emplacement et l'heure. Les listes d'élèves sont gérées via les ressources Élève, Enseignant et Invitation, ainsi que 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 utilisateurs autorisés à le créer et à le consulter. 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 pas spécifiques à un programme donné. 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. Les alias du namespace de domaine ne peuvent être créés que par les administrateurs de 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 sur les 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 métadonnées et des alias des cours, consultez Gérer les cours.

Listes de cours et utilisateurs

Students et Teachers sont des mises en correspondance spécifiques entre un profil utilisateur et un cours, qui représentent le rôle de cet utilisateur dans le cours. Les rôles d'élève et d'enseignant ne sont pas globaux: un utilisateur peut être désigné comme enseignant pour un cours et comme élève pour un autre. La désignation "étudiant" ou "enseignant" représente un ensemble d'autorisations pour un utilisateur donné dans un cours donné. Un cours peut avoir plusieurs enseignants ou aucun élève. Vous pouvez ajouter ou supprimer des enseignants et des élèves à un cours à tout moment.

Étudiants

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

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

les enseignants.

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

Les enseignants peuvent consulter et modifier les détails du cours, afficher les enseignants et les élèves, et gérer d'autres enseignants et élèves.

Invitations et les méthodes associées permettent d'ajouter facilement des élèves et des enseignants aux cours. Créer des invitations permet aux utilisateurs de choisir s'ils souhaitent 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ée par l'API Directory. L'utilisateur actuel peut également faire référence à son propre ID à l'aide de l'abréviation "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. Les représentants légaux dans Classroom ont accès à certaines informations sur les élèves, comme leurs devoirs.

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

Éléments de flux

Les éléments de flux sont les contenus publiés 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" dans l'interface utilisateur de Classroom. Les enseignants créent des CourseWork et des CourseWorkMaterials en cliquant sur le bouton Créer dans l'onglet "Travaux et devoirs". Les développeurs peuvent créer tous les types d'éléments de flux de manière automatisée via l'API Classroom.

Les éléments de flux sont les suivants:

  • Tous les éléments de flux peuvent contenir des ressources supplémentaires, telles que des fichiers Google Drive, des vidéos YouTube, Google Forms, des liens hypertextes vers des URL 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 de 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 module complémentaire Classroom.
  • Un élément de flux peut comporter des pièces jointes de plusieurs développeurs.
  • Les développeurs peuvent obtenir et modifier les informations sur n'importe quelle ressource d'élément de flux associée à l'un de leurs modules complémentaires.
  • Les développeurs peuvent rendre, récupérer ou renvoyer le travail 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 envoyés par des élèves individuels.

Éléments de flux copiés

Les enseignants peuvent copier un élément de flux en copiant un cours, en réutilisant un devoir ou en publiant un élément de flux dans plusieurs cours. Les nouvelles copies auront des identifiants distincts, 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.

Devoirs et devoirs rendus par les élèves

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 de flux pouvant accepter un envoi d'élève. Une ressource CourseWork contient des informations telles que la description, la date limite, la note maximale et des métadonnées telles que la date de création.

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

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

Le devoir d'un élève pour un élément CourseWork est représenté par un StudentSubmission. Il 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 éléments suivants:

  • Les feuilles de calcul et les pièces jointes envoyées pour un devoir, y compris leur titre, leur vignette 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 envoyés par les étudiants, consultez la section Gérer les devoirs.

CourseWorkMatériaux et annonces

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 des élèves de soumettre des artefacts. Par conséquent, aucune date limite n'est définie, et StudentSubmissions n'existe pas pour CourseWorkMaterials. Les enseignants peuvent utiliser CourseWorkMaterials pour publier des lectures suggérées, un programme ou le règlement de la classe.

Les Announcements représentent également du contenu partagé avec un groupe d'élèves, mais ne comportent pas de détails tels qu'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 sont utilisés pour organiser visuellement les CourseWork et les CourseWorkMaterials dans une classe. Vous pouvez les utiliser pour regrouper les devoirs en "facultatif" et "obligatoire", ou en "unité 1" et "unité 2", par exemple.

Modules complémentaires Classroom

Un module complémentaire est une interface utilisateur et un backend gérés par le développeur, généralement affichés dans un iFrame. Les modules complémentaires apparaissent sous la forme de pièces jointes sur un élément de 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 module complémentaire peuvent être une activité ou un contenu.

  • Les pièces jointes d'activités nécessitent que l'étudiant termine et remette une activité individuelle. Il peut s'agir, par exemple, de quiz, de dessins ou de jeux. Vous pouvez choisir de noter les devoirs.
  • 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. Exemples : photos, articles et vidéos.

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

Enregistrements

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

Pour en savoir plus, consultez le guide des notifications push.