Fonctionnement des requêtes

Cette page offre un aperçu du fonctionnement des requêtes dans l'API Google Classroom. L'objectif est d'aider les lecteurs qui ne connaissent pas encore la conception orientée ressources ni les API Google Workspace.

Pour obtenir des exemples de code spécifiques, consultez les guides d'API correspondants, par exemple Créer et gérer des cours ou Créer et gérer des cours.

Conception orientée ressources

Comme indiqué dans la section Structure de l'API, l'API Classroom suit les modèles de conception orientée ressources. La plupart des ressources disposent de méthodes pour les opérations standards telles que la création, la lecture, la modification et la suppression d'instances de la ressource.

Par exemple, vous pouvez create(), patch(), get(), list() et delete() un Course Classroom à l'aide de l'API.

Créer

Pour créer une ressource, comme un Course, appelez la méthode create() pour la ressource correspondante.

Les appels Create() nécessitent toujours les informations initiales et critiques de la ressource correspondante en entrée. Par exemple, pour créer un Course, appelez la méthode create() sur la ressource Course et spécifiez les name et description dans la requête, ainsi que des informations facultatives telles que le room.

Pour les sous-ressources (parfois appelées ressources enfants), les identifiants de la ressource parente sont également obligatoires. Par exemple, lors de la création d'un CourseWork dans un Course, le id Course est nécessaire pour déterminer à quel Course le CourseWork appartient.

Les méthodes Create() renvoient une instance de la ressource nouvellement créée dans la réponse de l'appel d'API. La ressource renvoyée comporte généralement des champs supplémentaires générés par le serveur, tels que la ressource id ou creationTime.

Correction

Pour modifier des ressources existantes, appelez la méthode patch() (parfois appelée update()) sur la ressource correspondante. La méthode patch() est presque identique à create(), avec deux différences principales. Lorsque vous appelez la méthode patch(), vous devez spécifier:

1. id de la ressource à modifier.
2. Liste de champs, appelée updateMask, permettant de déterminer les champs de la ressource à mettre à jour. Cette option est facultative lorsqu'il existe un ensemble de champs par défaut ou que les champs sont inférés.

Remarque :Vous remarquerez peut-être des méthodes update() à côté de méthodes patch(). Bien que les deux modifient une ressource, leur comportement diffère. Update() remplace complètement une ressource par une nouvelle, tandis que patch() ne met à jour que certains champs. Par exemple, courses.update() remplace l'intégralité d'un Course existant, tandis que courses.patch() utilise le fieldMask mentionné ci-dessus pour ne modifier que des champs spécifiques dans le Course. Pour simplifier, l'API Google Classroom utilise presque exclusivement patch(). Nous vous recommandons d'utiliser cette méthode en général.

Les méthodes Patch() renvoient l'instance complète de la ressource mise à jour dans la réponse de l'appel d'API, avec toutes les modifications effectuées.

Obtenir et lister

Il existe deux méthodes pour récupérer des ressources: get() et list().

La méthode get() récupère une ressource spécifique à l'aide d'un identifiant. Par exemple, récupérer un Course en fonction de id ou de alias. L'appel get() renvoie directement la ressource complète.

La méthode list() récupère plusieurs ressources du même type dans une seule requête, sans avoir besoin des identifiants de ressources individuels. L'opération list() récupère souvent toutes les sous-ressources d'une ressource parente, par exemple en récupérant tous les CourseWork d'une Course. Cela permet de réduire le nombre de requêtes par rapport à l'exécution de plusieurs appels get(). Cette approche est particulièrement utile lorsque vous ne connaissez pas le id des ressources souhaitées.

En général, les méthodes list() ont un nombre maximal de ressources pouvant être renvoyées en un seul appel. Des limites inférieures peuvent être configurées en incluant une valeur pageSize avec l'appel. Si le nombre de ressources dépasse la limite, la méthode list() prend en charge la pagination. Chaque "page" de résultats renvoyée fournit un pageToken, qui peut être inclus dans un appel list() ultérieur pour récupérer le prochain lot de ressources.

Supprimer

La méthode delete() accepte un identifiant de ressource, comme id, et supprime la ressource correspondante. Si l'delete() aboutit, une réponse vide est renvoyée.

Autres opérations

Toutes les opérations possibles avec l'API Classroom ne peuvent pas être effectuées avec les opérations standards mentionnées ci-dessus, par exemple, la modification des personnes auxquelles une ressource CourseWork est attribuée. Dans ce cas, des méthodes personnalisées sont disponibles, comme la méthode modifyAssignees. Le comportement de ces méthodes est personnalisé et vous devez consulter la documentation correspondante individuellement.