Introduction

L'API Google Docs vous permet de créer et de modifier des documents.

Les applications peuvent s'intégrer à l'API Docs pour créer des documents peaufinés à partir de données fournies par l'utilisateur et par le système. Grâce à cette API, vous pouvez:

  • Automatiser les processus
  • Créer des documents de manière groupée
  • Générer des factures ou des contrats

Présentation de l'API

La ressource documents fournit des méthodes pour appeler l'API Docs.

Méthodes d'API

Les méthodes suivantes vous permettent de créer, lire et mettre à jour des documents Google Docs:

  • Utilisez documents.create pour créer un document.
  • Utilisez documents.get pour récupérer le contenu d'un document spécifié.
  • Utilisez documents.batchUpdate pour effectuer de manière atomique un ensemble de mises à jour sur un document spécifié.

Les méthodes get et batchUpdate nécessitent un paramètre documentId (voir ci-dessous) pour spécifier le document cible. La méthode create renvoie une instance du document créé, à partir de laquelle vous pouvez lire l'ID.

Mises à jour groupées

La méthode batchUpdate prend une liste d'objets de requête et effectue les mises à jour dans le même ordre que dans la requête par lot. Les mises à jour par lot sont appliquées de manière atomique. Autrement dit, si une requête n'est pas valide, la mise à jour dans son ensemble échoue et aucune des modifications (potentiellement dépendantes) n'est appliquée.

La méthode batchUpdate renvoie une liste d'objets de réponse. Les objets de cette liste occupent le même ordre d'index que la requête correspondante.

Consultez les bonnes pratiques concernant les requêtes groupées pour découvrir comment regrouper les appels d'API par lot, ainsi que la documentation de référence de batchUpdate concernant les types de requêtes et de réponses.

ID du document

Les ID de document font référence à un document et peuvent être dérivés de l'URL:

https://docs.google.com/document/d/documentId/edit

Le documentId est une chaîne unique contenant des lettres, des chiffres et certains caractères spéciaux. L'expression régulière suivante peut être utilisée pour extraire l'ID d'un document à partir d'une URL Google Docs:

/document/d/([a-zA-Z0-9-_]+)

Si vous connaissez l'API Google Drive, documentId correspond à l'ID de la ressource File.

Emplacements dans un document: index

Lorsque vous mettez à jour le contenu d'un document, chaque mise à jour a lieu à un emplacement ou dans une plage du document. Ces emplacements et plages sont spécifiés à l'aide d'index, qui représentent un décalage au sein d'un segment de document conteneur. Pour en savoir plus sur les index et leur utilisation, consultez le guide conceptuel Structure d'un document Google Docs.

Workflow de mise à jour de documents

La création et le remplissage d'un nouveau document sont simples, car aucun contenu existant n'est à surveiller et aucun collaborateur ne peut modifier l'état du document. D'un point de vue conceptuel, cela fonctionne comme illustré dans le schéma de séquence suivant:

Workflow de création et de remplissage d'un nouveau document.

La mise à jour d'un document existant est plus complexe. Avant de pouvoir effectuer des appels pertinents pour mettre à jour un document, vous devez connaître son état actuel : quels sont ses éléments, leur contenu et leur emplacement dans le document. Le schéma séquentiel suivant montre comment cela fonctionne:

Workflow de mise à jour d'un document.

Ce schéma ne prend pas en compte les workflows dans lesquels des mises à jour simultanées effectuées par d'autres collaborateurs sont effectuées dans le même document. Pour en savoir plus à ce sujet, consultez la section Planifier la collaboration.