Ce guide présente les principales méthodes de requête et de réponse qui composent l'API Google Docs, et explique comment mettre à jour un document par lot.
Vous pouvez appeler l'API Google Docs à l'aide d'une requête HTTP ou en utilisant un appel de méthode dans une bibliothèque cliente spécifique à un langage. Ces deux méthodes sont globalement équivalentes.
L'API Google Docs renvoie une réponse HTTP, qui inclut généralement le résultat de l'appel de requête. Lorsque vous utilisez une bibliothèque cliente pour effectuer des requêtes, les réponses sont renvoyées d'une manière spécifique au langage.
Méthodes de requête
L'API Docs est compatible avec les méthodes suivantes :
documents.create: crée un document Google Docs vide.documents.get: renvoie une instance complète du document spécifié. Vous pouvez analyser le JSON renvoyé pour extraire le contenu, la mise en forme et d'autres fonctionnalités du document.documents.batchUpdate: envoie une liste de requêtes de modification à appliquer de manière atomique au document et renvoie 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 Document
ID.
Documents publiés
Vous ne pouvez pas utiliser la méthode documents.get pour récupérer des documents publiés. Une fois publiés, les documents publics utilisent un format d'URL différent avec un documentId public distinct. Les tentatives d'utilisation du documentId public avec la méthode documents.get renvoient un code d'état HTTP 404.
De même, vous ne pouvez pas utiliser la méthode de l'API Drive
files.copy pour copier un
document publié.
Pour récupérer ou copier un document publié, vous devez utiliser le documentId d'origine. Il n'existe aucune méthode permettant d'extraire le documentId d'origine à partir d'une URL publiée.
Pour en savoir plus, consultez les pages suivantes :
Mises à jour par lot
La
documents.batchUpdate
méthode accepte une liste d'
request objets,
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 les requêtes sont traitées dans l'ordre dans lequel elles apparaissent dans la requête par lot.
Toutes les requêtes de la mise à jour groupée sont appliquées de manière atomique. Autrement dit, si une requête n'est pas valide, l'ensemble de la mise à jour échoue et aucune des modifications (potentiellement dépendantes) n'est appliquée.
Certaines méthodes documents.batchUpdate fournissent des réponses contenant des informations sur les requêtes appliquées. Ces méthodes renvoient un corps
de
réponseresponse contenant une liste d'objets.
D'autres requêtes n'ont pas besoin de renvoyer des informations et affichent une réponse vide. Les objets de la liste de réponses occupent le même ordre d'index que la requête correspondante.
Un modèle courant pour effectuer des requêtes par lot se présente comme suit :
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Pour en savoir plus sur la mise en lot des appels de l'API Docs et sur les types de requêtes et de réponses, consultez les bonnes pratiques concernant les requêtes par lot et la
documents.batchUpdate
documentation de référence.
Opérations de mise à jour par lot
Il existe différents types de requêtes de mise à jour groupée. Voici une présentation 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