Hợp nhất văn bản vào tài liệu

Một ứng dụng hữu ích của API Google Tài liệu là hợp nhất thông tin từ một hoặc nhiều nguồn dữ liệu vào một tài liệu.

Trang này trình bày cách bạn có thể lấy dữ liệu từ một nguồn bên ngoài và chèn dữ liệu đó vào một tài liệu mẫu hiện có.

Mẫu là một loại tài liệu đặc biệt chứa cùng một văn bản cố định cho tất cả tài liệu được tạo từ mẫu, cùng với phần giữ chỗ được chỉ định nơi có thể đặt văn bản động khác. Ví dụ: mẫu hợp đồng có thể có nội dung cố định, cùng với các vị trí cho tên, địa chỉ và thông tin chi tiết khác của người nhận. Sau đó, ứng dụng của bạn có thể hợp nhất dữ liệu dành riêng cho khách hàng vào mẫu để tạo tài liệu hoàn chỉnh.

Có một số lý do khiến phương pháp này hữu ích:

  • Nhà thiết kế có thể dễ dàng điều chỉnh thiết kế của tài liệu bằng trình chỉnh sửa Google Tài liệu. Việc này dễ dàng hơn nhiều so với việc điều chỉnh các thông số trong ứng dụng để đặt bố cục đã kết xuất.

  • Việc tách nội dung khỏi bản trình bày là một nguyên tắc thiết kế phổ biến mang lại nhiều lợi ích.

Sơ đồ khái niệm về một quá trình hợp nhất.

Công thức cơ bản

Dưới đây là ví dụ về cách bạn có thể sử dụng API Tài liệu để hợp nhất dữ liệu vào một tài liệu:

  1. Tạo tài liệu bằng nội dung phần giữ chỗ để giúp bạn thiết kế và định dạng. Mọi định dạng văn bản bạn muốn thay thế đều được giữ nguyên.

  2. Đối với mỗi phần tử mà bạn sẽ chèn, hãy thay thế nội dung phần giữ chỗ bằng một thẻ. Hãy nhớ sử dụng các chuỗi không có khả năng xuất hiện bình thường. Ví dụ: {{account-holder-name}} có thể là một thẻ phù hợp.

  3. Trong mã, hãy sử dụng Google Drive API để tạo bản sao tài liệu.

  4. Trong mã, hãy sử dụng phương thức batchUpdate() của API Tài liệu với tên tài liệu và thêm ReplaceAllTextRequest.

Mã tài liệu tham chiếu đến một tài liệu và có thể được lấy từ URL

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

Ví dụ:

Hãy xem xét ví dụ sau đây, trong đó thay thế 2 trường trên tất cả các thẻ của mẫu bằng các giá trị thực để tạo tài liệu hoàn chỉnh.

Để thực hiện việc hợp nhất này, bạn có thể sử dụng mã bên dưới.

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

Quản lý mẫu

Đối với các tài liệu mẫu mà ứng dụng xác định và sở hữu, hãy tạo mẫu bằng một tài khoản chuyên dụng đại diện cho ứng dụng. Tài khoản dịch vụ là một lựa chọn phù hợp và giúp tránh các vấn đề phức tạp liên quan đến các chính sách của Google Workspace hạn chế việc chia sẻ.

Khi tạo các bản sao tài liệu từ mẫu, hãy luôn sử dụng thông tin xác thực của người dùng cuối. Điều này giúp người dùng có toàn quyền kiểm soát tài liệu thu được và ngăn các vấn đề về việc mở rộng quy mô liên quan đến hạn mức trên mỗi người dùng trong Drive.

Để tạo mẫu bằng tài khoản dịch vụ, hãy thực hiện các bước sau với thông tin xác thực ứng dụng:

  1. Tạo tài liệu bằng cách sử dụng hàm documents.create trong API Tài liệu.
  2. Cập nhật quyền để cho phép người nhận tài liệu đọc tài liệu đó bằng cách sử dụng permissions.create trong API Drive.
  3. Cập nhật quyền để cho phép tác giả mẫu ghi vào tệp đó bằng cách sử dụng permissions.create trong API Drive.
  4. Chỉnh sửa mẫu nếu cần.

Để tạo một thực thể của tài liệu, hãy thực hiện các bước sau với thông tin xác thực của người dùng:

  1. Tạo bản sao của mẫu bằng cách sử dụng files.copy trong API Drive.
  2. Thay thế các giá trị bằng cách sử dụng documents.batchUpdate trong API Tài liệu.