Ce guide présente les principales méthodes de requête et de réponse qui constituent l'API Google Docs, ainsi que la manière de mettre à jour un document par lot.
Vous pouvez appeler l'API Google Docs à l'aide d'une requête HTTP ou d'un appel de méthode dans une bibliothèque cliente spécifique à un langage. Ces deux options sont globalement équivalentes.
L'API Google Docs renvoie une réponse HTTP, qui inclut généralement le résultat de l'appel de la requête. Lorsque vous utilisez une bibliothèque cliente pour effectuer des requêtes, les réponses sont renvoyées de manière spécifique à la langue.
Méthodes de requête
L'API Docs est compatible avec les méthodes suivantes:
documents.create: créez un document Google Docs vierge.documents.get: renvoie une instance complète du document spécifié. Vous pouvez analyser le code JSON renvoyé pour extraire le contenu, la mise en forme et d'autres fonctionnalités du document.documents.batchUpdate: envoyez une liste de requêtes de modification à appliquer de manière atomique au document, puis renvoyez une liste de résultats.
Les méthodes documents.get et documents.batchUpdate nécessitent un documentId comme paramètre pour spécifier le document cible. La méthode documents.create renvoie une instance du document créé, à partir de laquelle vous pouvez lire le documentId. Pour en savoir plus sur documentId, consultez ID de document.
Mises à jour groupées
La méthode documents.batchUpdate prend une liste d'objets request, chacun spécifiant une seule requête à effectuer. Par exemple, mettez en forme un paragraphe, puis ajoutez une image intégrée. Chaque requête est validée avant d'être appliquée et traitée dans l'ordre dans lequel elle apparaît dans la requête par lot.
Toutes les requêtes de la mise à jour par lot sont appliquées de manière atomique. Autrement dit, si une requête n'est pas valide, la mise à jour entière échoue et aucune des modifications (potentiellement dépendantes) n'est appliquée.
Certaines méthodes documents.batchUpdate fournissent des réponses avec des informations sur les requêtes appliquées. Ces méthodes renvoient un corps de réponse contenant une liste d'objets response. Les autres requêtes n'ont pas besoin de renvoyer d'informations et de renvoyer une réponse vide. Les objets de la liste de réponse occupent le même ordre d'index que la requête correspondante.
Voici un modèle courant pour effectuer des requêtes par lot:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Consultez les bonnes pratiques concernant les requêtes par lot pour savoir comment regrouper vos appels d'API Docs, et la documentation de référence sur documents.batchUpdate pour connaître les types de requêtes et de réponses.
Opérations de mise à jour groupée
Il existe différents types de requêtes de mise à jour par lot. Voici une répartition des types de requêtes, regroupés en différentes catégories.
Articles associés
- Structure d'un document Google Docs
- Règles et comportement de modification structurelle
- Requêtes par lot