Unisci testo in un documento

Un'applicazione utile dell'API di Google Documenti è unire le informazioni da un o più origini dati in un documento.

Questa pagina illustra come inserire i dati da una sorgente esterna 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 designati in cui è possibile posizionare altro testo dinamico. Ad esempio, un modello di contratto potrebbe avere contenuti fissi, oltre a punti per il nome, l'indirizzo e altri dettagli. L'app può quindi unire nel modello dati specifici del cliente per creare documenti completati.

Questo approccio risulta utile per diversi motivi:

• Per i designer è facile perfezionare il design di un documento utilizzando l'editor di Documenti Google. È molto più semplice che regolare i parametri in dell'app per impostare il layout visualizzato.

• La separazione dei contenuti dalla presentazione è un'attività molto nota che offre molti vantaggi.

Una ricetta base

Ecco un esempio di come puoi utilizzare l'API Documenti per unire i dati in un documento:

1. Crea il tuo documento utilizzando segnaposto per aiutarti con la progettazione e la formattazione. La formattazione del testo da sostituire viene mantenuta.

2. Per ogni elemento da inserire, sostituisci i contenuti del segnaposto con un del tag. Assicurati di utilizzare stringhe che difficilmente si presentano normalmente. Ad esempio: {{account-holder-name}} potrebbe essere un buon tag.

3. Utilizza l'API Google Drive nel codice per creare una copia del documento.

4. Nel codice, utilizza il metodo batchUpdate() dell'API Documenti con il nome del documento e includi un ReplaceAllTextRequest.

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 tutte le schede di una modello con valori reali per generare un documento completo.

Per eseguire questa unione, puoi utilizzare il codice riportato di seguito.

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();

  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);
            });
      });

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()

Gestisci modelli

Per i documenti modello che l'applicazione definisce e possiede, crea utilizzando un account dedicato che rappresenta l'applicazione. Account di servizio sono una buona scelta ed evita complicazioni con i criteri di Google Workspace che puoi limitare la condivisione.

Quando crei istanze di documenti da modelli, utilizza sempre le credenziali dell'utente finale. Ciò offre agli utenti il controllo completo documento risultante e impedisce i problemi di scalabilità legati limiti in Drive.

Per creare un modello utilizzando un account di servizio, segui questi passaggi con le credenziali dell'applicazione:

1. Crea un documento utilizzando documents.create nell'API Documenti.
2. Aggiorna le autorizzazioni per consentire ai destinatari del documento di leggerlo utilizzando permissions.create in l'API Drive.
3. Aggiorna le autorizzazioni per consentire agli autori dei modelli di scrivere nei file utilizzando permissions.create in l'API Drive.
4. Modifica il modello come richiesto.

Per creare un'istanza del documento, segui questi passaggi con le credenziali utente:

1. Crea una copia del modello utilizzando files.copy nell'API Drive.
2. Sostituisci i valori con documents.batchUpdate nell'API Documenti.