Fonctionnement des requêtes

Cette page décrit de manière générale le fonctionnement des requêtes dans l'API Google Classroom. L'objectif est d'aider les lecteurs qui ne sont pas encore familiarisés avec la conception orientée ressources ou 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 devoirs.

Conception orientée ressources

Comme indiqué dans les ressources 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 mise à jour et la suppression d'instances de la ressource.

Par exemple, il est possible d'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 essentielles 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 name et description dans la requête, ainsi que des informations facultatives telles que room.

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

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

Correctif

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(), à deux différences près. 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. Ce paramètre est facultatif lorsqu'un ensemble de champs par défaut est défini ou lorsque les champs sont déduits.

Conseil : Vous remarquerez peut-être des méthodes update() à côté des 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 un Course existant dans son intégralité, tandis que courses.patch() utilise le fieldMask mentionné ci-dessus pour modifier uniquement des champs spécifiques dans le Course. Pour plus de simplicité, 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 à 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 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 dans un Course. Cela permet de minimiser les requêtes par rapport à l'exécution de plusieurs appels get(). C'est particulièrement utile lorsque vous ne connaissez pas le id des ressources souhaitées.

En général, les méthodes list() ont une quantité maximale 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. Dans les cas où le nombre de ressources dépasse la limite, la méthode list() est compatible avec 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 la requête 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, il n'est pas possible de modifier les responsables d'une ressource CourseWork. Dans ce cas, des méthodes personnalisées sont disponibles, comme la méthode modifyAssignees. Le comportement de ces méthodes est spécifique. Vous devez consulter la documentation pour chacune d'elles.