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 inserir em um documento de modelo.

Um modelo é um tipo especial de documento que contém o mesmo texto fixo para todos os documentos criados com base nele, além de marcadores de posição designados em que outro texto dinâmico pode ser colocado. Por exemplo, um modelo de contrato pode ter conteúdo fixo, além de espaços para o nome, endereço e outros detalhes do destinatário. Em seguida, o app pode mesclar dados específicos do cliente no modelo para criar documentos finais.

Essa abordagem é útil por vários motivos:

  • É fácil para os designers ajustar o design de um documento usando o editor dos Documentos Google. Isso é muito mais fácil do que ajustar parâmetros no app para definir o layout renderizado.

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

Diagrama conceitual de uma fusão.

Uma receita básica

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

  1. Crie seu documento usando conteúdo de marcador de posição para ajudar no design e na formatação. Toda formatação de texto que você quer substituir é preservada.

  2. Para cada elemento que você vai inserir, substitua o conteúdo do marcador de posição por uma tag. Use strings que provavelmente não vão ocorrer normalmente. Por exemplo, {{account-holder-name}} pode ser uma boa tag.

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

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

Os IDs de documentos referenciam 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 todas as guias de um modelo por valores reais para gerar um documento finalizado.

Para fazer essa fusão, 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<>();
// 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()

Gerenciar modelos

Para documentos de modelo que o aplicativo define e possui, crie o modelo usando uma conta dedicada que representa o aplicativo. As 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, sempre use credenciais de usuário final. Isso dá aos usuários controle total sobre o documento resultante e evita problemas de escalonamento relacionados aos limites por usuário no Drive.

Para criar um modelo usando uma conta de serviço, siga estas etapas 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 leiam o documento usando permissions.create na API Drive.
  3. Atualize as permissões para permitir que os criadores de modelos gravem nele usando permissions.create na API Drive.
  4. Edite o modelo conforme necessário.

Para criar uma instância do documento, siga estas etapas com as credenciais do 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.