Document

Ce guide présente des concepts tels que les principales méthodes qui composent l'API Google Docs, comment accéder à un document et le workflow à suivre lors de la création d'un document.

Méthodes d'API

La ressource documents fournit les méthodes que vous utilisez pour appeler l'API Docs. Les méthodes suivantes vous permettent de créer, de lire et de mettre à jour des documents Docs :

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

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 les requêtes et les méthodes de réponse de l'API Docs, consultez la section Requêtes et réponses.

ID du document

Le documentId est l'identifiant unique du document. Il peut être dérivé de l'URL d'un document. Il s'agit d'une chaîne spécifique contenant des lettres, des chiffres et certains caractères spéciaux. Les ID de document sont stables, même si le nom du document change.

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

L'expression régulière suivante peut être utilisée pour extraire le documentId d'une URL Google Docs :

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

Si vous connaissez l'API Google Drive, le documentId correspond à id dans la ressource files.

Gérer des documents dans Google Drive

Les fichiers Docs sont stockés dans Google Drive, notre service de stockage cloud. Bien que l'API Docs dispose de ses propres méthodes autonomes, il est souvent nécessaire d'utiliser également les méthodes de l'API Google Drive pour interagir avec les fichiers Docs d'un utilisateur. Par exemple, pour copier des fichiers Docs, utilisez la méthode files.copy de l'API Drive. Pour en savoir plus, consultez la section Copier un document existant.

Par défaut, lorsque vous utilisez l'API Docs, un nouveau document est enregistré dans le dossier racine de l'utilisateur sur Drive. Vous pouvez enregistrer un fichier dans un dossier Drive. Pour en savoir plus, consultez la section Utiliser des dossiers Google Drive.

Utiliser des fichiers Docs

Pour récupérer un document à partir de Mon Drive d'un utilisateur, il est souvent nécessaire d'utiliser d'abord la méthode files.list de Drive pour récupérer l'ID d'un fichier. L'appel de la méthode sans aucun paramètre renvoie une liste de tous les fichiers et dossiers de l'utilisateur, y compris les ID.

Le type MIME d'un document indique le type et le format des données. Le format de type MIME pour Docs est application/vnd.google-apps.document. Pour obtenir la liste des types MIME, consultez la section Types MIME compatibles avec Google Workspace et Google Drive.

Pour effectuer une recherche par type MIME uniquement pour les fichiers Docs dans Mon Drive, ajoutez le filtre de chaîne de requête suivant :

q: mimeType = 'application/vnd.google-apps.document'

Pour en savoir plus sur les filtres de chaîne de requête, consultez la section Rechercher des fichiers et des dossiers.

Une fois que vous connaissez le documentId, utilisez la documents.get méthode pour récupérer une instance complète du document spécifié. Pour en savoir plus, consultez la section Requêtes et réponses.

Pour exporter le contenu d'un document Google Workspace en octets, utilisez la méthode files.export de Drive avec le documentId du fichier à exporter et le type MIME d'exportation approprié. Pour en savoir plus, consultez la section Exporter le contenu d'un document Google Workspace.

Comparer les méthodes Get et List

Le tableau suivant décrit les différences entre les méthodes Drive et Docs, ainsi que les données renvoyées avec chacune d'elles :

Opérateur Description Utilisation
drive.files.get Obtient les métadonnées d'un fichier par ID. Renvoie une instance de la files ressource. Obtenir les métadonnées d'un fichier spécifique.
drive.files.list Obtient les fichiers d'un utilisateur. Renvoie une liste de fichiers. Obtenir la liste des fichiers d'un utilisateur lorsque vous ne savez pas quel fichier modifier.
docs.documents.get Obtient la dernière version du document spécifié, y compris toute la mise en forme et le texte. Renvoie une instance de la documents ressource. Obtenir le document pour un ID de document spécifique.

Workflow de création de documents

La création et le remplissage d'un nouveau document sont simples, car il n'y a pas de contenu existant à prendre en compte et aucun collaborateur ne peut modifier l'état du document. D'un point de vue conceptuel, cela fonctionne comme indiqué dans le diagramme de séquence suivant :

Workflow permettant de créer et de remplir un document.
Figure 1 : Workflow permettant de créer et de remplir un document.

Dans la figure 1, un utilisateur interagissant avec la ressource documents dispose du flux d'informations suivant :

  1. Une application appelle la documents.create méthode sur un serveur Web.
  2. Le serveur Web envoie une réponse HTTP contenant une instance du document créé en tant que ressource documents.
  3. Éventuellement, l'application appelle la documents.batchUpdate méthode pour effectuer de manière atomique un ensemble de requêtes de modification afin de remplir le document avec des données.
  4. Le serveur Web envoie une réponse HTTP. Certaines méthodes documents.batchUpdate fournissent un corps de réponse contenant des informations sur les requêtes appliquées, tandis que d'autres affichent une réponse vide.

Workflow de mise à jour de documents

La mise à jour d'un document existant est plus complexe. Avant de pouvoir effectuer des appels significatifs pour mettre à jour un document, vous devez connaître son état actuel : les éléments qui le composent, le contenu de ces éléments et l'ordre des éléments dans le document. Le diagramme de séquence suivant illustre ce fonctionnement :

Workflow permettant de mettre à jour un document.
Figure 2 : Workflow permettant de mettre à jour un document.

Dans la figure 2, un utilisateur interagissant avec la ressource documents dispose du flux d'informations suivant :

  1. Une application appelle la documents.get méthode sur un serveur Web, avec le documentId du fichier à rechercher.
  2. Le serveur Web envoie une réponse HTTP contenant une instance du document spécifié en tant que ressource documents. Le fichier JSON renvoyé contient le contenu, la mise en forme et d'autres fonctionnalités du document.
  3. L'application analyse le fichier JSON afin que l'utilisateur puisse déterminer le contenu ou le format à mettre à jour.
  4. L'application appelle la méthode documents.batchUpdate pour effectuer de manière atomique un ensemble de requêtes de modification afin de mettre à jour le document.
  5. Le serveur Web envoie une réponse HTTP. Certaines méthodes documents.batchUpdate fournissent un corps de réponse contenant des informations sur les requêtes appliquées, tandis que d'autres affichent une réponse vide.

Ce diagramme ne tient pas compte des workflows dans lesquels d'autres collaborateurs effectuent des mises à jour simultanées dans le même document. Pour en savoir plus, consultez la section Bonnes pratiques : planifier la collaboration.