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 khác 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 bằng 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ộ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ỉ và của người nhận 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ủa từng khách hàng vào mẫu đó để tạo tài liệu đã hoàn tất.
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 cách sử dụ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 của bạn để đặt bố cục được kết xuất.
Tách nội dung khỏi bản trình bày là một thiết kế nổi tiếng với nhiều lợi ích.
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 về 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 . 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à 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à chúng 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, ví dụ này thay thế 2 trường trên tất cả các thẻ của một có các giá trị thực để tạo một tài liệu đã hoàn tất.
Để 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 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 biệt đạ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à tránh được những rắc rối liên quan đến các chính sách của Google Workspace hạn chế 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 xác thực 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 kết quả và ngăn chặn các vấn đề mở rộng liên quan đế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 đă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 mẫu đó bằng permissions.create trong API Drive.
- Chỉnh sửa mẫu theo yêu cầu.
Để tạo một phiên bản của tài liệu, hãy thực hiện các bước sau đây 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ế giá trị bằng documents.batchUpdate trong API Tài liệu.