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 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ả các tài liệu được tạo từ mẫu, cùng với các 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ể đã chỉnh sửa nội dung, cùng với các vị trí cho tên, địa chỉ của người nhận và các thông tin chi tiết khác. Sau đó, ứng dụng của bạn có thể hợp nhất dữ liệu cụ thể của 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 tinh 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 tham số trong ứng dụng để thiết lập bố cục được kết xuất.
Tách biệt nội dung khỏi bản trình bày là một nguyên tắc thiết kế nổi tiếng với nhiều lợi ích.
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 tài liệu:
Bạn có thể tạo tài liệu bằng cách sử dụ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 mà bạn muốn thay thế đều được giữ nguyên.
Đố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 đảm bảo sử dụng các chuỗi ít có khả năng xảy ra bình thường. Ví dụ:
{{account-holder-name}}có thể là một thẻ phù hợp.Trong mã của bạn, hãy sử dụng API Google Drive để tạo bản sao của tài liệu.
Trong mã của bạn, hãy sử dụng phương thức
batchUpdate()của API Tài liệu cùng với tên tài liệu và thêmReplaceAllTextRequest.
Mã tài liệu tham chiếu đến một tài liệu và có thể lấy từ URL
https://docs.google.com/document/d/documentId/edit
Ví dụ:
Hãy xem xét ví dụ sau đây, thay thế 2 trường trong một mẫu bằng các giá trị thực để tạo một tài liệu hoàn chỉnh.
Để thực hiện 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<>();
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()
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 riêng sẽ đại diện cho ứng dụng. Tài khoản dịch vụ là lựa chọn phù hợp và tránh được các rắc rối nhờ các chính sách của Google Workspace hạn chế việc chia sẻ.
Khi bạn tạo bản sao tài liệu từ các 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 mang lại cho người dùng toàn quyền kiểm soát tài liệu kết quả và ngăn các vấn đề về tỷ lệ liên quan đến giới hạ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 bằng thông tin đăng nhập của ứng dụng:
- Tạo tài liệu bằng cách sử dụng documents.create trong API Tài liệu.
- 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.
- Cập nhật các quyền để cho phép tác giả mẫu ghi vào mẫu đó bằng cách sử dụng permissions.create trong API Drive.
- Chỉnh sửa mẫu theo yêu cầu.
Để tạo một bản sao của tài liệu, hãy thực hiện các bước sau bằng thông tin đăng nhập của người dùng:
- Tạo bản sao của mẫu bằng cách sử dụng files.copy trong API Drive.
- Thay thế các giá trị bằng documents.batchUpdate trong API Tài liệu.