La API de Documentos de Google te permite crear y modificar documentos.
Las apps se pueden integrar a la API de Documentos para crear documentos perfeccionados a partir de los datos del usuario y los proporcionados por el sistema. La API le permite hacer lo siguiente:
- Automatiza los procesos
- Crear documentación de forma masiva
- Generar facturas o contratos
Descripción general de la API
El recurso de documentos proporciona los métodos que utilizas para invocar la API de Documentos.
Métodos de la API
Los siguientes métodos te permiten crear, leer y actualizar documentos de Google Docs:
- Usa documents.create para crear un documento.
- Usa documents.get para recuperar el contenido de un documento especificado.
- Usa documents.batchUpdate para realizar actualizaciones atómicamente sobre un documento especificado.
Los métodos get y batchUpdate requieren un documentId (ver a continuación) como parámetro para especificar el documento de destino. El método create muestra una instancia del documento creado, desde la que puedes leer el ID.
Actualizaciones por lotes
El método batchUpdate toma una lista de objetos de solicitud y realiza actualizaciones según el 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, la actualización no tendrá éxito 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 índices que la solicitud correspondiente.
Consulta las prácticas recomendadas de solicitud por lotes para aprender a agrupar llamadas a la API y la documentación de referencia de batchUpdate para conocer los tipos de solicitud y respuesta.
ID de documento
Los ID de documento hacen referencia a un documento y se pueden derivar 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 de 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 Archivo.
Ubicaciones dentro de un documento: índices
Cuando realizas actualizaciones en 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 una compensación dentro de un segmento de documentos contenedor. Para obtener más información sobre los índices y cómo usarlos, consulta la guía conceptual de la Estructura de un documento de Google Docs.
Flujo de trabajo de actualización del documento
Crear y propagar un documento nuevo es sencillo, ya que no hay contenido para 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 poder realizar llamadas significativas para actualizar un documento, debes conocer su estado actual: qué elementos lo componen, qué contenido hay en esos elementos y dónde se ubican todos estos elementos dentro del documento. En el siguiente diagrama de secuencia, se muestra cómo funciona esto:
En este diagrama, no se tienen en cuenta los flujos de trabajo en los que se realizan actualizaciones simultáneas de otros colaboradores en el mismo documento. Consulta Planifica la colaboración para ver un análisis del tema.