API Google Tài liệu cho phép bạn tạo và sửa đổi tài liệu.
Các ứng dụng có thể tích hợp với API Tài liệu để tạo ra các tài liệu đẹp mắt từ cả dữ liệu do người dùng và hệ thống cung cấp. API này giúp bạn:
- Tự động hoá các quy trình
- Tạo tài liệu hàng loạt
- Tạo hoá đơn hoặc hợp đồng
Tổng quan về API
Tài nguyên tài liệu cung cấp các phương thức bạn dùng để gọi API Tài liệu.
Phương thức API
Các phương thức sau cho phép bạn tạo, đọc và cập nhật tài liệu trong Google Tài liệu:
- Sử dụng documents.create để tạo tài liệu.
- Sử dụng documents.get để truy xuất nội dung của một tài liệu được chỉ định.
- Sử dụng documents.batchUpdate để thực hiện một cách tỉ mỉ một nhóm nội dung cập nhật trên một tài liệu được chỉ định.
Phương thức get và batchUpdate yêu cầu phải có documentId (xem bên dưới) làm
tham số để chỉ định tài liệu mục tiêu. Phương thức create trả về một bản sao của tài liệu đã tạo, từ đó bạn có thể đọc mã.
Cập nhật theo đợt
Phương thức batchUpdate sẽ lấy danh sách các đối tượng yêu cầu và thực hiện các bản cập nhật
theo thứ tự mà chúng xuất hiện trong yêu cầu hàng loạt. Các bản cập nhật trong quá trình cập nhật theo lô được áp dụng không thể phân chia. Nghĩa là, nếu có yêu cầu không hợp lệ, thì toàn bộ quá trình cập nhật sẽ không thành công và sẽ không có thay đổi nào (có thể phụ thuộc) được áp dụng.
Phương thức batchUpdate trả về danh sách đối tượng phản hồi. Các đối tượng trong danh sách này chiếm cùng thứ tự chỉ mục với yêu cầu tương ứng.
Xem các phương pháp hay nhất về yêu cầu hàng loạt để biết cách phân nhóm các lệnh gọi API cùng nhau cũng như tài liệu tham khảo về batchUpdate cho các loại yêu cầu và phản hồi.
Mã tài liệu
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
documentId là một chuỗi duy nhất chứa chữ cái, số và một số ký tự đặc biệt. Bạn có thể sử dụng biểu thức chính quy sau đây để trích xuất
mã tài liệu từ URL của Google Tài liệu:
/document/d/([a-zA-Z0-9-_]+)
Nếu bạn đã quen thuộc với API Google Drive, documentId tương ứng với mã nhận dạng của tài nguyên Tệp.
Vị trí trong tài liệu: chỉ mục
Khi bạn cập nhật nội dung của một tài liệu, mỗi quá trình cập nhật sẽ diễn ra tại một vị trí hoặc trên một phạm vi trong tài liệu. Các vị trí và phạm vi này được chỉ định bằng cách sử dụng chỉ mục, thể hiện khoảng chênh lệch trong một phân đoạn tài liệu chứa. Để tìm hiểu thêm về chỉ mục và cách sử dụng chỉ mục, hãy xem hướng dẫn khái niệm về Cấu trúc của tài liệu Google Tài liệu.
Quy trình cập nhật tài liệu
Việc tạo và điền sẵn một tài liệu mới rất đơn giản vì không có nội dung nào phải lo lắng và không có cộng tác viên nào có thể thay đổi trạng thái tài liệu. Về mặt lý thuyết, hàm này hoạt động như minh hoạ trong sơ đồ trình tự sau:
Việc cập nhật tài liệu hiện có phức tạp hơn. Trước khi có thể thực hiện các lệnh gọi có ý nghĩa để cập nhật tài liệu, bạn cần biết trạng thái hiện tại của tài liệu: các thành phần được tạo nên, nội dung trong các thành phần đó và vị trí của tất cả các mục này trong tài liệu. Sơ đồ trình tự sau đây cho thấy cách hoạt động của quy trình này:
Sơ đồ này không xem xét quy trình công việc trong đó các cộng tác viên khác cập nhật đồng thời trong cùng một tài liệu. Hãy xem phần Lập kế hoạch cộng tác để biết thông tin thảo luận về chủ đề này.