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ả các tài liệu được tạo từ mẫu, cùng với phần giữ chỗ được chỉ định để có thể đặt văn bản động khác. Ví dụ: một mẫu hợp đồng có thể có nội dung cố định, cùng với các chỗ cho tên, địa chỉ của người nhận và các thông tin 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 vài 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. Cách 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 để đặt bố cục được kết xuất.
Việc tách nội dung khỏi bản trình bày là nguyên tắc thiết kế nổi tiếng với nhiều lợi ích.
Một công thức cơ bản
Sau đâ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:
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 mà bạn muốn thay thế đều được giữ nguyên.
Đối với mỗi phần tử 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 í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 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ác mã này 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: 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 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<>();
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 đạ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 bạn tránh những rắc rối do các chính sách của Google Workspace hạn chế hoạt động chia sẻ.
Khi bạn tạo các bản sao tài liệu từ mẫu, hãy luôn sử dụng thông tin đăng nhập của người dùng cuối. Điều này cho phép người dùng có toàn quyền kiểm soát tài liệu thu được và ngăn chặn các vấn đề về việc điều chỉnh tỷ lệ liên quan đến giới hạn cho 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 đăng nhập của ứng dụng:
- Tạo tài liệu bằ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 permissions.create trong API Drive.
- Cập nhật quyền để cho phép tác giả mẫu ghi vào đó 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 đây với 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.