Uma aplicação útil da API Google Docs é a mesclagem de 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 modelo já existente.
Um modelo é um tipo especial de documento que contém o mesmo texto fixo para todos os documentos criados a partir do modelo, com 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, com espaços para o nome, o endereço e outros detalhes do destinatário. 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 no app para definir o layout renderizado.
Separar conteúdo da apresentação é um princípio de design bem conhecido 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:
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.
Para cada elemento que você inserir, substitua o conteúdo do marcador por uma tag. Use strings que provavelmente não ocorrerão normalmente. Por exemplo,
{{account-holder-name}}
pode ser uma boa tag.No código, use a API Google Drive para fazer uma cópia do documento.
No código, use o método
batchUpdate()
da API Docs com o nome do documento e inclua umReplaceAllTextRequest
.
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. 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 a partir de 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:
- Crie um documento usando documents.create na API Docs.
- Atualize as permissões para permitir que os destinatários do documento leiam o arquivo usando permissions.create na API Drive.
- Atualize as permissões para permitir que os autores do modelo gravem nele usando permissions.create na API Drive.
- Edite o modelo conforme necessário.
Para criar uma instância do documento, execute as seguintes etapas com as credenciais de usuário:
- Crie uma cópia do modelo usando files.copy na API Drive.
- Substitua valores usando documents.batchUpdate na API Docs.