Unisci testo in un documento

Un'applicazione utile dell'API Google Docs è l'unione delle informazioni di una o più origini dati in un documento.

Questa pagina descrive come prendere 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 a partire dal modello, insieme a segnaposto designati 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 i dati specifici del cliente nel modello per creare documenti finiti.

Esistono diversi motivi per cui questo approccio è utile:

  • I progettisti possono perfezionare facilmente il design di un documento utilizzando l'editor di Documenti Google. È molto più semplice che regolare i parametri nell'app per impostare il layout di rendering.

  • La separazione dei contenuti dalla presentazione è un principio di progettazione ben noto con molti vantaggi.

Diagramma concettuale di un'unione.

Una ricetta di base

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

  1. Crea il documento utilizzando contenuti segnaposto per facilitare la progettazione e la formattazione. La formattazione del testo che vuoi sostituire viene mantenuta.

  2. Per ogni elemento che inserirai, sostituisci il contenuto segnaposto con un tag. Assicurati di utilizzare stringhe che è improbabile che si verifichino 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 Docs con il nome del documento e includi un ReplaceAllTextRequest.

Gli ID documento fanno riferimento a un documento e possono essere derivati dall'URL

https://docs.google.com/document/d/documentId/edit

Esempio

Considera il seguente esempio, che sostituisce due campi in tutte le schede di un modello con valori reali per generare un documento finito.

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. I service account sono una buona scelta ed evitano complicazioni con le norme 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 hanno il pieno controllo del documento risultante e si evitano problemi di scalabilità correlati ai limiti per utente in Drive.

Per creare un modello utilizzando un service account, esegui 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 dei modelli di scriverci utilizzando permissions.create nell'API Drive.
  4. Modifica il modello in base alle esigenze.

Per creare un'istanza del documento, esegui 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.