Una aplicación útil de la API de Documentos de Google es combinar información de una o más fuentes de datos en un documento.
En esta página, se describe cómo puedes tomar datos de una fuente externa para insertarlos en un documento de plantilla existente.
Una plantilla es un tipo especial de documento que contiene el mismo texto fijo para todos los documentos creados a partir de la plantilla, junto con marcadores de posición designados en los que se puede colocar otro texto dinámico. Por ejemplo, una plantilla de contrato puede tener contenido fijo, junto con espacios para el nombre, la dirección y otros detalles del receptor. Luego, tu app puede combinar datos específicos del cliente en la plantilla para crear documentos terminados.
Existen varias razones por las que este enfoque resulta útil:
Los diseñadores pueden optimizar el diseño de un documento con el editor de Documentos de Google con facilidad. Esto es mucho más fácil que ajustar los parámetros de tu app para configurar el diseño renderizado.
Separar el contenido de la presentación es un principio de diseño conocido que tiene muchos beneficios.
Una receta básica
Este es un ejemplo de cómo puedes usar la API de Documentos para combinar datos en un documento:
Crea tu documento con contenido de marcadores de posición que te ayude con el diseño y el formato. Se conservará cualquier formato de texto que desees reemplazar.
Para cada elemento que insertarás, reemplaza el contenido del marcador de posición por una etiqueta. Asegúrate de usar strings que probablemente no aparezcan normalmente. Por ejemplo,
{{account-holder-name}}podría ser una buena etiqueta.En tu código, usa la API de Google Drive para hacer una copia del documento.
En tu código, usa el método
batchUpdate()de la API de Documentos con el nombre del documento y, además, incluye unReplaceAllTextRequest.
Los IDs de documento hacen referencia a un documento y pueden derivarse de la URL.
https://docs.google.com/document/d/documentId/edit
Ejemplo
Considera el siguiente ejemplo, en el que se reemplazan 2 campos en una plantilla con valores reales para generar un documento terminado.
Para realizar esta combinación, puedes usar el código que aparece a continuación.
Java
String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());
List<Request> requests = new ArrayList<>();
requests.add(new Request()
.setReplaceAllText(new ReplaceAllTextRequest()
.setContainsText(new SubstringMatchCriteria()
.setText("{{customer-name}}")
.setMatchCase(true))
.setReplaceText(customerName)));
requests.add(new Request()
.setReplaceAllText(new ReplaceAllTextRequest()
.setContainsText(new SubstringMatchCriteria()
.setText("{{date}}")
.setMatchCase(true))
.setReplaceText(date)));
BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(documentId, body.setRequests(requests)).execute();
Node.js
let customerName = 'Alice';
let date = yyyymmdd()
let requests = [
{
replaceAllText: {
containsText: {
text: '{{customer-name}}',
matchCase: true,
},
replaceText: customerName,
},
},
{
replaceAllText: {
containsText: {
text: '{{date}}',
matchCase: true,
},
replaceText: date,
},
},
];
google.options({auth: auth});
google
.discoverAPI(
'https://docs.googleapis.com/$discovery/rest?version=v1&key={YOUR_API_KEY}')
.then(function(docs) {
docs.documents.batchUpdate(
{
documentId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
resource: {
requests,
},
},
(err, {data}) => {
if (err) return console.log('The API returned an error: ' + err);
console.log(data);
});
});
Python
customer_name = 'Alice'
date = datetime.datetime.now().strftime("%y/%m/%d")
requests = [
{
'replaceAllText': {
'containsText': {
'text': '{{customer-name}}',
'matchCase': 'true'
},
'replaceText': customer_name,
}}, {
'replaceAllText': {
'containsText': {
'text': '{{date}}',
'matchCase': 'true'
},
'replaceText': str(date),
}
}
]
result = service.documents().batchUpdate(
documentId=document_id, body={'requests': requests}).execute()
Administrar plantillas
Para los documentos de plantilla que la aplicación define y posee, crea la plantilla con una cuenta dedicada que represente a la aplicación. Las cuentas de servicio son una buena opción y evitan complicaciones con las políticas de Google Workspace que restringen el uso compartido.
Cuando crees instancias de documentos a partir de plantillas, usa siempre credenciales de usuario final. Esto brinda a los usuarios control total sobre el documento resultante y evita problemas de escalamiento relacionados con los límites por usuario en Drive.
Para crear una plantilla con una cuenta de servicio, realiza los siguientes pasos con las credenciales de la aplicación:
- Crea un documento con documents.create en la API de Documentos.
- Actualiza los permisos para permitir que los destinatarios del documento puedan leerlo con permissions.create en la API de Drive.
- Actualiza los permisos para permitir que los autores de plantillas escriban en ella con permissions.create en la API de Drive.
- Edita la plantilla según sea necesario.
Para crear una instancia del documento, realiza los siguientes pasos con las credenciales de usuario:
- Crea una copia de la plantilla usando files.copy en la API de Drive.
- Reemplaza los valores con documents.cord en la API de Documentos.