La API de Documentos de Google te permite crear y modificar documentos.
Las apps se pueden integrar con la API de Documentos para crear documentos refinados a partir de datos proporcionados por el usuario y por el sistema. La API te permite hacer lo siguiente:
- Automatizar procesos
- Crear documentación de forma masiva
- Generar facturas o contratos
Descripción general de la API
El recurso documents proporciona métodos que puedes usar para invocar la API de Documentos.
Métodos de la API
Los siguientes métodos te permiten crear, leer y actualizar archivos de Documentos de Google:
- Usa documents.create para crear un documento.
- Usa documents.get para recuperar el contenido de un documento específico.
- Usa documents.batchUpdate para realizar de forma atómica un conjunto de actualizaciones en un documento específico.
Los métodos get y batchUpdate requieren un documentId (consulta a continuación) como parámetro para especificar el documento de destino. El método create muestra una instancia del documento creado, desde el que puedes leer el ID.
Actualizaciones por lotes
El método batchUpdate toma una lista de objetos de solicitud y realiza actualizaciones en función del mismo orden en el que aparecen en la solicitud por lotes. Las actualizaciones en la actualización por lotes se aplican de forma atómica. Es decir, si alguna solicitud no es válida, no se completará correctamente la actualización y no se aplicará ninguno de los cambios (potencialmente dependientes).
El método batchUpdate muestra una lista de objetos de respuesta. Los objetos de esta lista ocupan el mismo orden de índice que la solicitud correspondiente.
Consulta las prácticas recomendadas para las solicitudes por lotes a fin de obtener información sobre cómo agrupar las llamadas a la API y la documentación de referencia de batchUpdate para los tipos de solicitud y respuesta.
ID de documento
Los IDs de documento hacen referencia a un documento y pueden derivarse de la URL:
https://docs.google.com/document/d/documentId/edit
documentId es una string única que contiene letras, números y algunos caracteres especiales. La siguiente expresión regular se puede usar para extraer el ID de documento desde una URL de Documentos de Google:
/document/d/([a-zA-Z0-9-_]+)
Si estás familiarizado con la API de Google Drive, documentId corresponde al ID del recurso File.
Ubicaciones dentro de un documento: índices
Cuando actualizas el contenido de un documento, cada actualización se realiza en una ubicación o en un rango dentro del documento. Estas ubicaciones y rangos se especifican mediante índices, que representan un desplazamiento dentro de un segmento de documento contenedor. Para obtener más información sobre los índices y cómo usarlos, consulta la guía conceptual Estructura de un documento de Documentos de Google.
Flujo de trabajo de la actualización de documentos
Crear y propagar un documento nuevo es sencillo, ya que no hay contenido existente por el que preocuparse y no hay colaboradores que puedan modificar el estado del documento. En teoría, esto funciona como se muestra en el siguiente diagrama de secuencia:
Actualizar un documento existente es más complejo. Antes de que puedas realizar llamadas importantes para actualizar un documento, debes conocer su estado actual: qué elementos lo componen, qué contenido tienen y dónde se ubican todos estos elementos dentro del documento. En el siguiente diagrama de secuencias, se muestra cómo funciona:
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. Consulta Cómo planificar la colaboración para ver un análisis de este tema.