Un'applicazione utile dell'API Documenti Google è quella di unire le informazioni di una o più origini dati in un documento.
Questa pagina illustra come recuperare i dati da un'origine esterna e inserirli in un documento modello esistente.
Un modello è un tipo speciale di documento che contiene lo stesso testo fisso per tutti i documenti creati a partire dal modello, insieme a segnaposto designati in cui è possibile posizionare altro testo dinamico. Ad esempio, un modello di contratto potrebbe avere contenuti fissi, oltre a spazi per il nome, l'indirizzo e altri dettagli del destinatario. L'app può quindi unire i dati specifici dei clienti nel modello per creare documenti completi.
Questo approccio è utile per diversi motivi:
Per i designer è facile perfezionare il design di un documento utilizzando l'editor di Documenti Google. È molto più facile rispetto all'ottimizzazione dei parametri nell'app per impostare il layout di cui è stato eseguito il rendering.
Separare i contenuti dalla presentazione è un principio di progettazione ben noto con molti vantaggi.
Una ricetta semplice
Ecco un esempio di come puoi utilizzare l'API Docs per unire i dati in un documento:
Crea il documento utilizzando contenuti segnaposto che ti aiutino con la progettazione e il formato. La formattazione del testo che vuoi sostituire viene mantenuta.
Per ogni elemento che intendi inserire, sostituisci i contenuti del segnaposto con un tag. Assicurati di utilizzare stringhe che difficilmente si verificano normalmente. Ad esempio,
{{account-holder-name}}potrebbe essere un tag valido.Nel codice, usa l'API Google Drive per creare una copia del documento.
Nel codice, utilizza il metodo
batchUpdate()dell'API Docs con il nome del documento e includi unReplaceAllTextRequest.
Gli ID documento fanno riferimento a un documento e possono essere ricavati dall'URL
https://docs.google.com/document/d/documentId/edit
Esempio
Considera l'esempio seguente, che sostituisce 2 campi in un modello con valori reali per generare un documento completato.
Per eseguire questa unione, puoi utilizzare il codice riportato di seguito.
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()
Gestisci modelli
Per i documenti del modello che l'applicazione definisce e possiede, crea il modello utilizzando un account dedicato che rappresenta l'applicazione. Gli account di servizio sono una buona scelta ed evita complicazioni con i criteri di Google Workspace che limitano la condivisione.
Quando crei istanze di documenti dai modelli, utilizza sempre le credenziali dell'utente finale. In questo modo gli utenti possono avere il controllo completo del documento risultante ed evita i problemi di scalabilità relativi ai limiti per utente in Drive.
Per creare un modello utilizzando un account di servizio, esegui i passaggi seguenti con le credenziali dell'applicazione:
- Creare un documento utilizzando documents.create nell'API Documenti.
- Aggiorna le autorizzazioni per consentire ai destinatari del documento di leggerlo utilizzando permissions.create nell'API Drive.
- Aggiorna le autorizzazioni per consentire agli autori del modello di scrivere utilizzando permissions.create nell'API Drive.
- Modifica il modello in base alle tue esigenze.
Per creare un'istanza del documento, segui questi passaggi con le credenziali utente:
- Crea una copia del modello utilizzando files.copy nell'API Drive.
- Sostituisci i valori utilizzando documents.batchUpdate nell'API Documenti.