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 une invocation de méthode dans une bibliothèque cliente spécifique à un langage. Elles 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 envoyer 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ée un document Google Docs vide.documents.get: Renvoie une instance complète du document spécifié. Vous pouvez analyser le fichier JSON renvoyé pour extraire le contenu, la mise en forme et d'autres caractéristiques du document.documents.batchUpdate: envoyez une liste de demandes de modification à appliquer de manière atomique au document et 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 du document.
Notez que vous ne pouvez pas utiliser la méthode documents.get pour récupérer les documents publiés. Une fois publiés, les documents publics utilisent un format d'URL différent. Toute tentative d'utilisation du nouveau documentId de l'URL avec la méthode documents.get renvoie un code d'état HTTP 404. Il n'existe aucune méthode permettant de récupérer le documentId d'origine à partir de l'URL publiée. Pour contourner ce problème, vous pouvez utiliser l'API Drive pour copier le document publié dans un document partagé, puis accéder à ce fichier à la place. Pour en savoir plus, consultez Rendre Google Docs, Sheets, Slides et Forms publics.
Mises à jour groupées
La méthode documents.batchUpdate accepte 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. 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 par lot sont appliquées de manière atomique. Autrement dit, si une requête n'est pas valide, la mise à jour échoue dans son ensemble 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éponse contenant une liste d'objets response.
Les autres requêtes n'ont pas besoin de renvoyer d'informations et doivent afficher une réponse vide. Les objets de la liste de réponses occupent le même ordre d'index que la requête correspondante.
Voici un exemple de 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 obtenir tous les détails sur la façon de regrouper vos appels à l'API Docs et la documentation de référence documents.batchUpdate pour les types de requêtes et de réponses.
Opérations de mise à jour par lot
Il existe différents types de requêtes de mise à jour par lot. Voici une présentation des types de demandes, regroupés dans différentes catégories.
Articles associés
- Structure d'un document Google Docs
- Règles et comportement de la modification structurelle
- Requêtes par lot