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 coletar dados de uma fonte externa e inseri-los em um documento de modelo.
Um modelo é um tipo especial de documento que contém o mesmo texto fixo para todos os documentos criados a partir dele, 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. O app pode mesclar dados específicos do cliente no modelo para criar documentos finalizados.
Essa abordagem é útil por diversos motivos:
É fácil para os designers ajustar detalhes de 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 o conteúdo da apresentação é um princípio de design conhecido que gera muitos benefícios.
Uma receita básica
Confira um exemplo de como usar a API Docs para mesclar dados em um documento:
Crie seu documento usando o conteúdo de marcador de posição para ajudar no design e formato. Todas as formatações de texto que você quer substituir são preservadas.
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 ocorreriam 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 documentos 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 um modelo por valores reais para gerar um documento finalizado.
Para realizar 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<>();
// 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 definidos e de propriedade do aplicativo, crie o modelo usando uma conta dedicada que represente o aplicativo. As contas de serviço são uma boa escolha 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 as credenciais do usuário final. Isso dá aos usuários controle total sobre o documento resultante e evita problemas de dimensionamento 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 o leiam 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, siga estas etapas com as credenciais do usuário:
- Crie uma cópia do modelo usando files.copy na API Drive.
- Substitua os valores usando documents.batchUpdate na API Docs.