Unisci testo in un documento

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

Questa pagina illustra come estrarre i 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 designati dove è possibile inserire 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 del cliente nel modello per creare i documenti finali.

Questo approccio è 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 nella tua app per impostare il layout visualizzato.

  • Separare i contenuti dalla presentazione è un principio di design ben noto con molti vantaggi.

Diagramma concettuale di un'unione.

Una ricetta di base

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

  1. Crea il documento utilizzando contenuti segnaposto per aiutarti con il design e il formato. La formattazione del testo che vuoi sostituire viene conservata.

  2. Per ogni elemento che inserirai, 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 buon tag.

  3. Nel codice, utilizza l'API Google Drive 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

Prendi in considerazione il seguente esempio, che sostituisce due campi in tutte le schede di 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<>();
// 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()

Gestisci modelli

Per i documenti modello definiti e di proprietà dell'applicazione, crea il modello utilizzando un account dedicato che rappresenta l'applicazione. Gli account di servizio sono una buona scelta ed evitano 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 pieno controllo sul documento risultante e si evitano i problemi di scalabilità relativi ai limiti per utente in Drive.

Per creare un modello utilizzando un account di servizio, svolgi i seguenti passaggi con le credenziali dell'applicazione:

  1. Crea un documento utilizzando documents.create nell'API Docs.
  2. Aggiorna le autorizzazioni per consentire ai destinatari del documento di leggerlo utilizzando permissions.create nell' API Drive.
  3. Aggiorna le autorizzazioni per consentire agli autori del modello di scrivere utilizzando permissions.create nell' API Drive.
  4. Modifica il modello in base alle esigenze.

Per creare un'istanza del documento, svolgi i seguenti passaggi con le credenziali utente:

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