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 soignés à partir de données fournies par l'utilisateur et par le système. L'API vous permet de:
- Automatiser les processus
- Créer des documents de façon groupée
- Générer des factures ou des contrats
Présentation de l'API
La ressource documents fournit des méthodes permettant d'appeler l'API Docs.
Méthodes d'API
Les méthodes suivantes vous permettent de créer, de lire et de 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é.
- La méthode documents.batchUpdate permet d'effectuer de façon 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 duquel vous pouvez lire l'ID.
Mises à jour par lot
La méthode batchUpdate prend une liste d'objets de requête et effectue les mises à jour dans l'ordre dans lequel elles apparaissent 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, l'intégralité de la mise à jour é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 par lot pour savoir comment effectuer des appels d'API par lot et la documentation de référence batchUpdate pour 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 obtenus à partir de l'URL:
https://docs.google.com/document/d/documentId/edit
documentId est une chaîne unique contenant des lettres, des chiffres et des caractères spéciaux. L'expression régulière suivante peut être utilisée pour extraire l'ID du document 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 modifiez le contenu d'un document, chaque mise à jour a lieu à un emplacement ou sur une plage du document. Ces zones et plages sont spécifiées à l'aide d'index, qui représentent un décalage dans un segment de documents. Pour en savoir plus sur les index et leur utilisation, consultez le guide conceptuel Structure d'un document Google Docs.
Workflow de mise à jour des documents
Il est très facile de créer et d'insérer un nouveau document, car il n'y a aucun contenu à craindre 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:
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 éléments le composent, quel est le contenu de ces éléments, et où se trouvent tous ces éléments dans le document. Le schéma de séquence suivant montre comment cela fonctionne:
Ce schéma ne prend pas en compte les workflows dans lesquels des mises à jour simultanées par d'autres collaborateurs sont effectuées dans le même document. Pour en savoir plus à ce sujet, consultez la page Planifier la collaboration.