Documento

En esta guía, se presentan conceptos como los métodos principales que conforman la API de Google Docs, cómo acceder a un documento y el flujo de trabajo cuando se crea un documento.

Métodos de la API

El recurso documents proporciona métodos que usas 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 la que puedes leer el documentId. Para obtener más información sobre las solicitudes y los métodos de respuesta de la API de Documentos, consulta Solicitudes y respuestas.

ID de documento

documentId es el identificador único del documento y se puede obtener de la URL de un documento. Es una cadena particular que contiene letras, números y algunos caracteres especiales. Los IDs de los documentos son estables, incluso si cambia el nombre del documento.

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

La siguiente expresión regular se puede usar para extraer el documentId de una URL de Documentos de Google:

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

Si conoces 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 es necesario usar también los 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. Existen 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 Mi unidad de un usuario, a menudo es necesario usar primero el método files.list de Drive para recuperar el ID de un archivo. Si llamas al método sin ningún parámetro, se muestra una lista de todos los archivos y carpetas, incluidos los IDs, del usuario.

El tipo de MIME de un documento indica el tipo y el formato de los datos. El formato del tipo de MIME para 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 GDrive, 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 cadenas de consulta, consulta Cómo buscar 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 el contenido de bytes de un documento de Google Workspace, usa el método files.export de Drive con el documentId del archivo que deseas exportar y el tipo MIME de exportación correcto. Para obtener más información, consulta Cómo exportar el 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 Obtén 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 los archivos del usuario cuando no sepas qué archivo debes modificar.
docs.documents.get Obtiene la versión más reciente del documento especificado, incluido todo el formato y el texto. Muestra una instancia del recurso documents. Obtén el documento de un ID de documento específico.

Flujo de trabajo de creación de documentos

Crear y propagar un documento nuevo es sencillo, ya que no hay contenido existente por el que preocuparse ni colaboradores que puedan alterar el estado del documento. Conceptualmente, esto funciona como se muestra en el siguiente diagrama de secuencia:

Flujo de trabajo para crear y propagar un documento nuevo.
Figura 1. Flujo de trabajo para crear y propagar un documento nuevo.

En la Figura 1, un usuario que interactúa con el recurso documents tiene el siguiente flujo de información:

  1. Una app llama al método documents.create en un servidor web.
  2. El servidor web envía una respuesta HTTP que contiene una instancia del documento creado como un recurso documents.
  3. 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 el documento con datos.
  4. 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

La actualización de un documento existente es más compleja. Antes de poder realizar llamadas significativas para actualizar un documento, debes conocer su estado actual: qué elementos lo componen, qué contenido contienen esos elementos y el orden de los elementos dentro del documento. En el siguiente diagrama de secuencias, se muestra cómo funciona:

Flujo de trabajo para actualizar un documento.
Figura 2. Flujo de trabajo para actualizar un documento.

En la Figura 2, un usuario que interactúa con el recurso documents tiene el siguiente flujo de información:

  1. Una app llama al método documents.get en un servidor web con el documentId del archivo que se debe encontrar.
  2. 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 del documento, el formato y otras funciones.
  3. La app analiza el JSON para que el usuario pueda determinar qué contenido o formato actualizar.
  4. 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.
  5. 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 consideran los flujos de trabajo en los que otros colaboradores realizan actualizaciones simultáneas en el mismo documento. Para obtener más información, consulta la sección de prácticas recomendadas Planifica la colaboración.