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 los métodos que usas para invocar la API de Documentos. Los siguientes métodos te permiten crear, leer y actualizar documentos de Documentos de Google:

  • Usa la documents.create. método para crear un documento.
  • Usa el método documents.get para recuperar el contenido de un documento especificado.
  • Usa la documents.batchUpdate. para realizar de forma atómica un conjunto de actualizaciones en un documento específico.

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 devuelve una instancia del documento creado, desde donde puedes leer el documentId Para obtener más información sobre las solicitudes a la API de Documentos y métodos de respuesta, consulta Solicitudes y de respuestas ante incidentes.

ID de documento

El documentId es el identificador único del documento y se puede derivar desde la URL de un documento. Es una cadena particular que contiene letras, números y algunos caracteres especiales. Los ID de documento son estables, incluso si el nombre del documento cambios.

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

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

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

Si ya 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 almacenamiento basado en la nube servicio. Si bien la API de Documentos tiene sus propios métodos independientes, es una tarea necesario usar también los métodos de la API de Google Drive para interactuar con el Archivos de Documentos. Por ejemplo, para copiar archivos de Documentos, usa API de Drive files.copy . Para obtener más información, consulta Cómo copiar un archivo en un documento.

De forma predeterminada, cuando usas la API de Documentos de Google, se guarda un documento nuevo en la la carpeta raíz del usuario en Drive. Existen opciones para guardar un archivo a una carpeta de Drive. Para obtener más información, consulta Trabaja 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, se suele necesario para usar por primera vez files.list para recuperar las Es el ID de un archivo. Si llamas al método sin ningún parámetro, se muestra una lista de todos archivos y carpetas, incluidos los IDs, del usuario.

El tipo de MIME de un documento indica el tipo y formato de datos. El formato de tipo de MIME para Documentos es application/vnd.google-apps.document. Para obtener una lista de Tipos de MIME; consulta MIME compatibles con Google Workspace y Google Drive de la API de Google Ads.

Para buscar por tipo MIME solo en archivos de Documentos en Mi Drive, 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 documentos de Google Workspace, usa la carpeta files.export con el elemento documentId del archivo que se exportará y el MIME de exportación correcto tipo. Para obtener más información, consulta Exporta Documento de Google Workspace contenido.

Compara los métodos Get y List

En la siguiente tabla, se describen las diferencias entre los de Documentos de Google, y los datos que se devuelven 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. Si no sabes qué archivo debes modificar, obtén una lista de los archivos del usuario.
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 de un ID de documento específico.

Flujo de trabajo de la creación de documentos

Crear y completar un documento nuevo es sencillo, ya que no hay hay contenido existente del que preocuparse y no hay colaboradores que puedan modificar el estado del documento. De forma conceptual, esto funciona como se muestra en la siguiente secuencia diagrama:

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

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

  1. Una aplicación llama al Método documents.create activado un servidor web.
  2. El servidor web envía una respuesta HTTP que contiene una instancia del Se creó el documento como recurso documents.
  3. De manera opcional, la app llama a documents.batchUpdate. para realizar de forma atómica un conjunto de solicitudes de edición para completar el documento con los 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 otras muestran una respuesta vacía.

Flujo de trabajo para la actualización de documentos

Actualizar un documento existente es más complejo. Antes de que puedas realizar cambios llamadas para actualizar un documento, debes conocer su estado actual: qué elementos qué contenido tienen, así como el orden de estos el documento. En el siguiente diagrama de secuencias, se muestra cómo funciona:

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

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

  1. Una aplicación llama al Método documents.get en una Web con los documentId del archivo que se buscarán.
  2. El servidor web envía una respuesta HTTP que contiene una instancia del documento especificado como un recurso documents. El JSON que se devuelve contiene el el contenido del documento, el formato y otras características.
  3. La app analiza el JSON para que el usuario pueda determinar qué contenido o formato actualización.
  4. La app llama al método documents.batchUpdate para realizar un conjunto de forma atómica 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 otras muestran una respuesta vacía.

Este diagrama no considera flujos de trabajo en los que actualizaciones simultáneas de otros se hacen colaboradores en el mismo documento. Para obtener más información, consulta la sección de prácticas recomendadas: Planifica colaboración.