Mesclar texto em um documento

Uma aplicação útil da API Google Docs é mesclar informações de uma ou mais fontes de dados em um documento.

Nesta página, descrevemos como extrair dados de uma fonte externa e inseri-los em um documento de modelo existente.

Um modelo é um tipo especial de documento que contém o mesmo texto fixo para todos os documentos criados a partir do modelo, bem como marcadores designados onde outros textos dinâmicos podem ser colocados. Por exemplo, um modelo de contrato pode ter um conteúdo fixo, com espaços para o nome do destinatário, o endereço e outros detalhes. Seu app pode mesclar dados específicos do cliente no modelo para criar documentos finalizados.

Essa abordagem é útil por vários motivos:

  • Os designers facilmente ajustam o design de um documento usando o Editor do Documentos Google. Isso é muito mais fácil do que ajustar parâmetros no seu app para definir o layout renderizado.

  • Separar o conteúdo da apresentação é um princípio de design bem conhecido que tem muitos benefícios.

Diagrama conceitual de uma mesclagem.

Uma receita básica

Veja um exemplo de como usar a API Docs para mesclar dados em um documento:

  1. Crie seu documento usando conteúdo de marcador para ajudar com o design e o formato. Qualquer formatação de texto que você queira substituir é preservada.

  2. Para cada elemento inserido, substitua o conteúdo do marcador por uma tag. Use strings que têm pouca probabilidade de ocorrer normalmente. Por exemplo, {{account-holder-name}} pode ser uma boa tag.

  3. No código, use a API Google Drive para fazer uma cópia do documento.

  4. No código, use o método batchUpdate() da API Docs com o nome do documento e inclua um ReplaceAllTextRequest.

Os IDs de documento fazem referência a um documento e podem ser derivados do URL

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

Exemplo

Considere o exemplo a seguir, que substitui dois campos em um modelo por valores reais para gerar um documento finalizado.

Para fazer essa mesclagem, use o código abaixo.

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

Gerenciar modelos

Para documentos de modelo que o aplicativo define e possui, crie o modelo usando uma conta dedicada que represente o aplicativo. Contas de serviço são uma boa opção e evitam complicações com as políticas do Google Workspace que restringem o compartilhamento.

Ao criar instâncias de documentos com base em modelos, use sempre credenciais de usuário final. Com isso, os usuários têm controle total sobre o documento resultante e evitam problemas de escalonamento relacionados aos limites por usuário no Drive.

Para criar um modelo usando uma conta de serviço, execute as etapas a seguir com as credenciais do aplicativo:

  1. Crie um documento usando documents.create na API Docs.
  2. Atualize as permissões para permitir que os destinatários do documento leiam o documento usando permissions.create na API Drive.
  3. Use permissions.create na API Drive para atualizar as permissões para que os autores do modelo façam gravações nele.
  4. Edite o modelo conforme necessário.

Para criar uma instância do documento, execute as etapas a seguir com as credenciais de usuário:

  1. Crie uma cópia do modelo usando files.copy na API Drive.
  2. Substitua os valores usando documents.batchUpdate na API Docs.