Document

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

Méthodes d'API

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

  • Utilisez le documents.create pour créer un document.
  • Utiliser la méthode documents.get pour récupérer le contenu d'un document spécifié.
  • Utilisez le documents.batchUpdate 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 documentId Pour en savoir plus sur les méthodes de requête et de réponse de l'API Docs, consultez la section Requêtes et réponses.

ID du document

documentId est l'identifiant unique du document. Il peut être obtenu à partir de l'URL d'un document. Il s'agit d'une chaîne particulière contenant des lettres, des chiffres et certains caractères spéciaux. Les ID de document sont stables, même si leur nom des modifications.

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, documentId correspond à id dans la ressource files.

Gérez des documents dans Google Drive.

Les fichiers Docs sont stockés dans Google Drive, notre espace de stockage dans le cloud Google Cloud. Bien que l'API Docs dispose de ses propres méthodes autonomes, elle est souvent d'utiliser les méthodes de l'API Google Drive pour interagir avec les données Fichiers Docs. Par exemple, pour copier des fichiers Docs, utilisez files.copy de l'API Drive . Pour en savoir plus, consultez la section Copier un fichier existant document.

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

Travailler avec des fichiers Docs

Pour récupérer un document du dossier Mon Drive d'un utilisateur, pour utiliser d'abord les fonctionnalités files.list pour récupérer ID d'un fichier. L'appel de la méthode sans paramètre renvoie une liste de tous les fichiers et dossiers, y compris les ID, de l'utilisateur.

Le type MIME d'un document indique le type et le format des données. Le format du type MIME pour Docs est application/vnd.google-apps.document. Pour obtenir une liste les types MIME, consultez l'article Protocoles MIME pris en charge par Google Workspace et Google Drive différents types d'appareil.

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 plus d'informations sur les filtres de chaîne de requête, voir Rechercher des fichiers et dossiers.

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

Pour exporter le contenu d'octets d'un document Google Workspace, utilisez files.export avec la documentId du fichier à exporter et la bonne exportation MIME type. Pour en savoir plus, consultez la section Exporter Document Google Workspace contenus.

Comparez les méthodes Get et List.

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

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

Workflow de création de documents

La création et le remplissage d'un document sont simples, car il n'y a pas contenus existants dont il faut se soucier et aucun collaborateur ne peut modifier le l'état du document. Sur le plan conceptuel, cela fonctionne comme le montre la séquence suivante diagramme:

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

Dans la figure 1, un utilisateur interagissant avec La ressource documents dispose des éléments suivants : flux d'informations:

  1. Une application appelle la méthode Méthode documents.create activée un serveur Web.
  2. Le serveur Web envoie une réponse HTTP contenant une instance du document créé en tant que ressource documents.
  3. L'application peut éventuellement appeler la méthode documents.batchUpdate. permettant d'exécuter de manière atomique un ensemble de requêtes de modification afin de remplir le document avec les données.
  4. Le serveur Web envoie une réponse HTTP. Quelques méthodes documents.batchUpdate fournir un corps de réponse avec des informations sur les requêtes appliquées, tandis que d'autres renvoient une réponse vide.

Workflow de mise à jour des documents

Il est plus complexe de mettre à jour un document existant. Avant de pouvoir prendre des décisions pour mettre à jour un document, vous devez connaître son état actuel: quels éléments créent le contenu de ces éléments, et l'ordre des éléments à l'intérieur le document. Le schéma séquentiel suivant illustre ce fonctionnement:

Workflow de mise à jour document.
Figure 2. Workflow de mise à jour d'un document.

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

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

Ce diagramme ne prend pas en compte les workflows dans lesquels d'autres collaborateurs effectuent des mises à jour simultanées dans le même document. Pour en savoir plus, consultez les bonnes pratiques bonnes pratiques Planifier la collaboration.