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.

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

Um modelo é um tipo especial de documento que contém o mesmo texto fixo para todos os documentos criados com base no modelo, 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, junto com espaços para o nome, 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:

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

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

Um roteiro básico

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

1. Crie seu documento usando conteúdo marcador de posição para ajudar você com o design e o formato. A formatação do texto que você quiser substituir será preservada.

2. Para cada elemento que você inserir, substitua o conteúdo do marcador por um tag. Use strings que provavelmente não ocorrerão 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 do nome do documento e incluem 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 todas as guias de uma com valores reais para gerar um documento finalizado.

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

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

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 escolha e evita complicações com as políticas do Google Workspace que e restringir 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 documento resultante e evita problemas de escalonamento relacionados a limites no Drive.

Para criar um modelo usando uma conta de serviço, siga estas etapas com as credenciais do aplicativo:

1. Criar um documento usando documents.create na API Docs.
2. Atualize as permissões para que os destinatários do documento leiam o documento usando o permissions.create em a API Drive.
3. Atualize as permissões para que os autores de modelos façam gravações nele usando permissions.create em a 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 valores usando documents.batchUpdate na API Docs.