Una aplicación útil de la API de Documentos de Google es combinar información o más fuentes de datos en un documento.
En esta página, se describe cómo puedes tomar datos de una fuente externa y, luego, insertarlos en un documento de plantilla existente.
Una plantilla es un tipo especial de documento que contiene el mismo texto fijo en todos los documentos creados a partir de ella, junto con marcadores de posición designados. donde 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. Luego, tu app podrá combinar datos específicos del cliente en la plantilla. para crear documentos terminados.
Existen varias razones por las cuales este enfoque resulta útil:
Es fácil para los diseñadores ajustar el diseño de un documento usando el editor de Documentos de Google. Esto es mucho más fácil que ajustar los parámetros en tu app para configurar el diseño renderizado.
Separar el contenido de la presentación es un diseño conocido con 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 el contenido de marcadores de posición para ayudarte con el diseño y el formato. El formato de texto que quieras reemplazar se conserva.
Por cada elemento que insertarás, reemplaza el contenido del marcador de posición con una etiqueta. Asegúrate de usar cadenas que tienen pocas probabilidades de ocurrir normalmente. Por ejemplo:
{{account-holder-name}}
podría ser una buena etiqueta.En tu código, usa la API de Google Drive para crear una copia del documento.
En tu código, usa el método
batchUpdate()
de la API de Documentos con el nombre del documento e incluir unReplaceAllTextRequest
Los IDs de documento hacen referencia a un documento y pueden derivar de la URL
https://docs.google.com/document/d/documentId/edit
Ejemplo
Considera el siguiente ejemplo, que reemplaza 2 campos en todas las pestañas de un plantilla con valores reales para generar un documento terminado.
Para realizar esta combinación, puedes usar el siguiente código.
Java
String customerName = "Alice"; DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd"); String date = formatter.format(LocalDate.now()); List<Request> requests = new ArrayList<>(); // One option for replacing all text is to specify all tab IDs. requests.add(new Request() .setReplaceAllText(new ReplaceAllTextRequest() .setContainsText(new SubstringMatchCriteria() .setText("{{customer-name}}") .setMatchCase(true)) .setReplaceText(customerName) .setTabsCriteria(new TabsCriteria() .addTabIds(TAB_ID_1) .addTabIds(TAB_ID_2) .addTabIds(TAB_ID_3)))); // Another option is to omit TabsCriteria if you are replacing across all tabs. 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 = [ // One option for replacing all text is to specify all tab IDs. { replaceAllText: { containsText: { text: '{{customer-name}}', matchCase: true, }, replaceText: customerName, tabsCriteria: { tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3], }, }, }, // Another option is to omit TabsCriteria if you are replacing across all tabs. { 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 = [ # One option for replacing all text is to specify all tab IDs. { 'replaceAllText': { 'containsText': { 'text': '{{customer-name}}', 'matchCase': 'true' }, 'replaceText': customer_name, 'tabsCriteria': { 'tabIds': [TAB_ID_1, TAB_ID_2, TAB_ID_3], }, }}, # Another option is to omit TabsCriteria if you are replacing across all tabs. { '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 usando una cuenta dedicada que representa la aplicación. Cuentas de servicio son una buena opción y evitan complicaciones con las políticas de Google Workspace que restringir uso compartido.
Cuando crees instancias de documentos a partir de plantillas, usa siempre credenciales de usuario final. Esto les da a los usuarios control total documento resultante y evita los problemas de escalamiento límites en Drive.
Para crear una plantilla con una cuenta de servicio, sigue estos pasos con las credenciales de la aplicación:
- Crea un documento usando documents.create en la API de Documentos.
- Actualiza los permisos para permitir que los destinatarios del documento lo lean con permissions.create, la API de Drive.
- Actualiza los permisos para permitir que los autores de plantillas escriban en ella permissions.create, la API de Drive.
- Edita la plantilla según sea necesario.
Para crear una instancia del documento, sigue estos pasos: con las credenciales de usuario:
- Crea una copia de la plantilla usando files.copy en la API de Drive
- Reemplazar valores con documents.batchUpdate en la API de Documentos.