En esta guía, se presentan conceptos como los métodos principales que conforman la API de Documentos de Google, cómo acceder a un documento y el flujo de trabajo para crear un documento.
Métodos de la API
El recurso documents
proporciona los métodos que puedes usar para invocar la API de Documentos. Los siguientes métodos te permiten crear, leer y actualizar documentos de Documentos:
- Usa el método
documents.create
para crear un documento. - Usa el método
documents.get
para recuperar el contenido de un documento especificado. - Usa el método
documents.batchUpdate
para realizar de forma atómica un conjunto de actualizaciones en un documento especificado.
Los métodos documents.get
y documents.batchUpdate
requieren un documentId
como parámetro para especificar el documento de destino. El método documents.create
muestra una instancia del documento creado, desde el que puedes leer el
documentId
. Para obtener más información sobre las solicitudes a la API de Documentos y los métodos de respuesta, consulta Solicitudes y respuestas.
ID de documento
documentId
es el identificador único del documento y se puede derivar de su URL. Es una cadena particular que contiene letras, números y algunos caracteres especiales. Los IDs de documento son estables, incluso si cambia su nombre.
https://docs.google.com/document/d/DOCUMENT_ID/edit
La siguiente expresión regular se puede usar para extraer documentId
de la URL de Documentos de Google:
/document/d/([a-zA-Z0-9-_]+)
Si estás familiarizado con la API de Google Drive, documentId
corresponde a id
en el recurso files
.
Administra tus documentos en Google Drive.
Los archivos de Documentos se almacenan en Google Drive, nuestro servicio de almacenamiento basado en la nube. Si bien la API de Documentos tiene sus propios métodos independientes, a menudo también
debes usar métodos de la API de Google Drive para interactuar con los archivos
de Documentos de un usuario. Por ejemplo, para copiar archivos de Documentos, usa el método files.copy
de la API de Drive. Para obtener más información, consulta Cómo copiar un documento existente.
De forma predeterminada, cuando se usa la API de Documentos, se guarda un documento nuevo en la carpeta raíz del usuario en Drive. Hay opciones para guardar un archivo en una carpeta de Drive. Para obtener más información, consulta Cómo trabajar con carpetas de Google Drive.
Cómo trabajar con archivos de Documentos
Para recuperar un documento de la sección Mi unidad de un usuario, a menudo
es necesario usar primero el método files.list
de Drive para recuperar el
ID del archivo. Si llamas al método sin ningún parámetro, se muestra una lista de todos los archivos y las carpetas, incluidos los ID, del usuario.
El tipo de MIME de un documento indica el tipo y el formato de los datos. El formato de tipo de MIME de Documentos es application/vnd.google-apps.document
. Para obtener una lista de los tipos de MIME, consulta Tipos de MIME compatibles con Google Workspace y Google Drive.
Para buscar solo archivos de Documentos por tipo de MIME en Mi unidad, agrega el siguiente filtro de cadena de consulta:
q: mimeType = 'application/vnd.google-apps.document'
Para obtener más información sobre los filtros de cadena de consulta, consulta Busca archivos y carpetas.
Una vez que conozcas el documentId
, usa el método
documents.get
para recuperar
una instancia completa del documento especificado. Para obtener más información, consulta Solicitudes y respuestas.
Para exportar contenido de bytes de documentos de Google Workspace, usa el método files.export
de Drive con el documentId
del archivo que deseas exportar y el tipo de MIME de exportación correcto. Para obtener más información, consulta Exporta contenido de documentos de Google Workspace.
Compara los métodos Get
y List
En la siguiente tabla, se describen las diferencias entre los métodos de Drive y Documentos, y los datos que se muestran con cada uno:
Operador | Descripción | Uso |
---|---|---|
drive.files.get |
Obtiene los metadatos de un archivo por ID. Muestra una instancia del recurso files . |
Obtén los metadatos de un archivo específico. |
drive.files.list |
Obtiene los archivos de un usuario. Muestra una lista de archivos. | Obtén una lista de archivos del usuario cuando no sepas con seguridad cuál debes modificar. |
docs.documents.get |
Obtiene la versión más reciente del documento especificado, incluidos todo el formato y el texto. Muestra una instancia del recurso documents . |
Obtén el documento para un ID de documento específico. |
Flujo de trabajo para la creación de documentos
Crear y propagar un documento nuevo es sencillo, ya que no hay contenido existente por el que debas preocuparte y tampoco hay colaboradores que puedan alterar el estado del documento. Conceptualmente, esto funciona como se muestra en el siguiente diagrama de secuencia:
En la Figura 1, un usuario que interactúa con el recurso documents
tiene el siguiente flujo de información:
- Una app llama al método
documents.create
en un servidor web. - El servidor web envía una respuesta HTTP que contiene una instancia del documento creado como un recurso
documents
. - De manera opcional, la app llama al método
documents.batchUpdate
para realizar de forma atómica un conjunto de solicitudes de edición para propagar datos en el documento. - El servidor web envía una respuesta HTTP. Algunos métodos
documents.batchUpdate
proporcionan un cuerpo de respuesta con información sobre las solicitudes aplicadas, mientras que otros muestran una respuesta vacía.
Flujo de trabajo de actualización de documentos
Actualizar un documento existente es más complejo. Antes de realizar llamadas significativas para actualizar un documento, debes conocer su estado actual: qué elementos lo componen, qué contenido tienen y su orden. En el siguiente diagrama de secuencias, se muestra cómo funciona esto:
En la Figura 2, un usuario que interactúa con el recurso documents
tiene el siguiente flujo de información:
- Una app llama al método
documents.get
en un servidor web, con eldocumentId
del archivo que se debe buscar. - El servidor web envía una respuesta HTTP que contiene una instancia del documento especificado como un recurso
documents
. El JSON que se muestra contiene el contenido, el formato y otras características del documento. - La app analiza el JSON para que el usuario pueda determinar qué contenido o formato actualizar.
- La app llama al método
documents.batchUpdate
para realizar de forma atómica un conjunto de solicitudes de edición para actualizar el documento. - El servidor web envía una respuesta HTTP. Algunos métodos
documents.batchUpdate
proporcionan un cuerpo de respuesta con información sobre las solicitudes aplicadas, mientras que otros muestran una respuesta vacía.
En este diagrama, no se tienen en cuenta los flujos de trabajo en los que las actualizaciones simultáneas de otros colaboradores se realizan en el mismo documento. Para obtener más información, consulta la sección de prácticas recomendadas Planifica la colaboración.
Temas relacionados
- Estructura de un documento de Documentos de Google
- Solicitudes y respuestas
- Comportamiento y reglas de edición estructurales
- Prácticas recomendadas para obtener los mejores resultados