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 requêtes API Docs et
méthodes de réponse, consultez la section Requêtes et réponses
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
des 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 les
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. Conceptuellement, cela fonctionne comme le montre la séquence suivante diagramme:
Dans la figure 1, un utilisateur interagissant avec
La ressource documents
dispose des éléments suivants :
flux d'informations:
- Une application appelle la méthode
Méthode
documents.create
activée un serveur Web. - Le serveur Web envoie une réponse HTTP qui contient une instance du
a créé un document en tant que ressource
documents
. - 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. - 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:
Dans la figure 2, un utilisateur interagissant avec la ressource documents
dispose de la
flux d'informations suivant:
- Une application appelle la méthode
Méthode
documents.get
sur un Web avec ledocumentId
du fichier à rechercher. - 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, la mise en forme et d'autres fonctionnalités des documents. - L'application analyse le fichier JSON afin que l'utilisateur puisse déterminer le contenu ou le format à mise à jour.
- 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. - 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 des mises à jour simultanées par d'autres collaborateurs travaillent dans le même document. Pour en savoir plus, consultez les bonnes pratiques bonnes pratiques Planifier la collaboration.
Articles associés
- Structure d'un document Google Docs
- Requêtes et réponses
- Règles et comportement de modification structurelle
- Bonnes pratiques pour de meilleurs résultats