将文本合并到文档中

Google 文档 API 的一项实用应用是将一个或多个数据源中的信息合并到文档中。

本页概述了如何从外部来源获取数据并将其插入现有模板文档中。

模板是一种特殊类型的文档，其中包含从模板创建的所有文档的相同固定文本，以及可放置其他动态文本的指定占位符。例如，合同模板可能包含固定内容，以及用于填写收货人姓名、地址和其他详细信息的位置。然后，您的应用可以将客户专用数据合并到模板中，以创建完成的文档。

这种方法非常有用，原因有以下几点：

• 设计师可以轻松使用 Google 文档编辑器优化文档的设计。这比在应用中调整参数来设置呈现的布局要容易得多。

• 将内容与呈现分离是一项众所周知的设计原则，具有诸多优势。

基本食谱

下面的示例展示了如何使用 Docs API 将数据合并到文档中：

1. 使用占位符内容创建文档，以帮助您设计和设置格式。您要替换的所有文本格式都会保留。

2. 对于要插入的每个元素，请将占位符内容替换为标记。请务必使用不太可能在正常情况下出现的字符串。例如，{{account-holder-name}} 可能是一个不错的标记。

3. 在代码中，使用 Google Drive API 复制文档。

4. 在代码中，使用 Docs API 的 batchUpdate() 方法和文档名称，并添加 ReplaceAllTextRequest。

文档 ID 引用文档，可从网址派生

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

为提高效率，您可以在同一批量更新请求中执行多次替换。如需了解如何批量处理 API 调用，请参阅批处理请求最佳实践

示例

请考虑以下示例，其中将模板的所有标签页中的 2 个字段替换为实际值，以生成完成的文档。

如需执行此合并，您可以使用以下代码。

JavaNode.jsPython 更多

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

注意： 对于包含多个标签页的文档，ReplaceAllTextRequest 默认会应用于所有标签页。如需详细了解如何使用标签页，请参阅请求文档。

管理模板

对于应用定义并拥有的模板文档，请使用代表该应用的专用账号创建模板。服务账号是不错的选择，可避免因 Google Workspace 政策限制共享而产生复杂问题。

使用模板创建文档实例时，请始终使用最终用户凭据。这样，用户就可以完全控制生成的文档，并防止与云端硬盘中的每位用户限制相关的扩缩问题。

如需使用服务账号创建模板，请使用应用凭据执行以下步骤：

1. 在文档 API 中使用 documents.create 创建文档。
2. 更新权限，以允许文档收件人使用云端硬盘 API 中的 permissions.create 读取文档。
3. 更新权限，以允许模板作者使用云端硬盘 API 中的 permissions.create 对其进行写入。
4. 根据需要修改模板。

如需创建文档实例，请使用用户凭据执行以下步骤：

1. 使用 Drive API 中的 files.copy 创建模板的副本。
2. 在 Docs API 中使用 documents.batchUpdate 替换值。