Un'applicazione utile dell'API Documenti Google è l'unione di informazioni da una o più origini dati in un documento.
Questa pagina illustra come prelevare dati da un'origine esterna e inserirli in un documento modello esistente.
Un modello è un tipo speciale di documento contenente lo stesso testo fisso per tutti i documenti creati dal modello, insieme a segnaposto in cui è possibile inserire altro testo dinamico. Ad esempio, un modello di contratto potrebbe avere contenuti fissi, insieme a spazi per il nome, l'indirizzo e altri dettagli del destinatario. L'app può quindi unire nel modello dati specifici del cliente per creare documenti completati.
Questo approccio risulta utile per diversi motivi:
L'editor di documenti Google consente ai designer di perfezionare facilmente il design di un documento. È molto più facile che regolare i parametri nell'app per impostare il layout visualizzato.
Separare i contenuti dalla presentazione è un noto principio di progettazione con molti vantaggi.
Una ricetta base
Ecco un esempio di come puoi utilizzare l'API Documenti per unire i dati in un documento:
Crea il tuo documento utilizzando contenuti segnaposto per la progettazione e la formattazione. La formattazione del testo che vuoi sostituire viene mantenuta.
Per ogni elemento da inserire, sostituisci i contenuti del segnaposto con un tag. Assicurati di utilizzare stringhe che difficilmente si presentano normalmente. Ad esempio,
{{account-holder-name}}potrebbe essere un buon tag.Utilizza l'API Google Drive nel codice per creare una copia del documento.
Nel codice, utilizza il metodo
batchUpdate()dell'API Documenti 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 due campi in un modello con valori reali per generare un documento completo.
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 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 da modelli, utilizza sempre le credenziali dell'utente finale. In questo modo gli utenti hanno il controllo completo sul documento risultante e si evitano problemi di scalabilità legati ai limiti per utente in Drive.
Per creare un modello utilizzando un account di servizio, esegui questi passaggi con le credenziali dell'applicazione:
- Crea 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 dei modelli di scrivere utilizzando permissions.create nell'API Drive.
- Modifica il modello come richiesto.
Per creare un'istanza del documento, esegui 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.