Hướng dẫn này giới thiệu các khái niệm như các phương thức chính tạo nên API Google Tài liệu, cách truy cập tài liệu và quy trình làm việc khi tạo tài liệu.
Phương thức API
Tài nguyên documents
cung cấp
mà bạn dùng để gọi API Tài liệu. Các phương thức sau đây cho phép bạn tạo, đọc và cập nhật tài liệu trên Docs:
- Sử dụng
documents.create
để tạo tài liệu. - Sử dụng phương thức
documents.get
để truy xuất nội dung của một tài liệu đã chỉ định. - Sử dụng phương thức
documents.batchUpdate
để thực hiện một tập hợp các bản cập nhật trên một tài liệu đã chỉ định.
Các phương thức documents.get
và documents.batchUpdate
yêu cầu có documentId
làm tham số để chỉ định tài liệu đích. Phương thức documents.create
sẽ trả về một phiên bản của tài liệu đã tạo để bạn có thể đọc
documentId
. Để biết thêm thông tin về các yêu cầu API Tài liệu và
phương thức phản hồi, hãy xem Yêu cầu và
.
Mã tài liệu
documentId
là giá trị nhận dạng duy nhất của tài liệu và có thể lấy được
từ URL của một tài liệu. Đó là một chuỗi cụ thể chứa chữ cái, số và
một số ký tự đặc biệt. Mã tài liệu là ổn định, ngay cả khi tên tài liệu
thay đổi.
https://docs.google.com/document/d/DOCUMENT_ID/edit
Biểu thức chính quy sau đây có thể được dùng để trích xuất documentId
từ một
URL 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 id
trong tài nguyên files
.
Quản lý tài liệu trong Google Drive
Các tệp Tài liệu được lưu trữ trong Google Drive, dịch vụ lưu trữ dựa trên đám mây của chúng tôi. Mặc dù API Tài liệu có các phương thức độc lập riêng, nhưng bạn cũng thường phải sử dụng các phương thức API Google Drive để tương tác với các tệp Tài liệu của người dùng. Ví dụ: để sao chép tệp Tài liệu, hãy sử dụng
files.copy
của API Drive
. Để biết thêm thông tin, hãy xem phần Sao chép tệp hiện có
tài liệu.
Theo mặc định, khi bạn sử dụng API Tài liệu, một tài liệu mới sẽ được lưu vào thư mục gốc của người dùng trên Drive. Có các lựa chọn để lưu tệp vào một thư mục trên Drive. Để biết thêm thông tin, hãy xem phần Hợp tác với Thư mục trên Google Drive.
Làm việc với các tệp Tài liệu
Để truy xuất tài liệu từ phần Drive của tôi của người dùng, thông thường
để sử dụng
files.list
để truy xuất
Mã nhận dạng của một tệp. Việc gọi phương thức không có bất kỳ tham số nào sẽ trả về danh sách tất cả
tệp và thư mục, bao gồm cả mã nhận dạng, cho người dùng.
Loại MIME của tài liệu cho biết loại và định dạng dữ liệu. Định dạng loại MIME
cho Tài liệu là application/vnd.google-apps.document
. Để biết danh sách các loại MIME, hãy xem bài viết Các loại MIME được Google Workspace và Google Drive hỗ trợ.
Để chỉ tìm kiếm theo loại MIME cho các tệp Tài liệu trong trang Drive, hãy thêm bộ lọc chuỗi truy vấn sau đây:
q: mimeType = 'application/vnd.google-apps.document'
Để biết thêm thông tin về bộ lọc chuỗi truy vấn, hãy xem Tìm kiếm tệp và các thư mục.
Sau khi bạn biết documentId
, hãy sử dụng
Phương thức documents.get
để truy xuất
một bản sao hoàn chỉnh của tài liệu được chỉ định. Để biết thêm thông tin, hãy xem
Yêu cầu và phản hồi.
Để xuất nội dung byte tài liệu trên Google Workspace, hãy dùng
files.export
bằng phần tử
documentId
tệp cần xuất và xuất MIME chính xác
. Để biết thêm thông tin, hãy xem bài viết Xuất
Tài liệu trên Google Workspace
.
So sánh các phương thức Get
và List
Bảng sau đây mô tả sự khác biệt giữa Drive và phương thức Tài liệu và dữ liệu được trả về bằng mỗi phương thức:
Đơn vị tổ chức | Mô tả | Cách sử dụng |
---|---|---|
drive.files.get |
Lấy siêu dữ liệu của tệp theo mã nhận dạng. Trả về một thực thể của tài nguyên files . |
Lấy siêu dữ liệu cho một tệp cụ thể. |
drive.files.list |
Lấy tệp của người dùng. Trả về danh sách các tệp. | Nhận danh sách các tệp của người dùng khi bạn không biết chắc tệp nào mà bạn phải sửa đổi. |
docs.documents.get |
Tải phiên bản mới nhất của tài liệu được chỉ định, bao gồm tất cả định dạng và văn bản. Trả về một thực thể của tài nguyên documents . |
Tải tài liệu cho một mã tài liệu cụ thể. |
Quy trình tạo tài liệu
Việc tạo và điền sẵn tài liệu mới rất đơn giản vì không có nội dung hiện có để 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, trình tự này hoạt động như sau sơ đồ:
Trong Hình 1., người dùng tương tác với
Tài nguyên documents
có những phần sau
luồng thông tin:
- Một ứng dụng gọi hàm
Phương thức
documents.create
đang bật máy chủ web. - Máy chủ web gửi phản hồi HTTP có chứa một phiên bản của
tài liệu đã tạo dưới dạng tài nguyên
documents
. - Nếu muốn, ứng dụng sẽ gọi
documents.batchUpdate
để thực hiện từng yêu cầu chỉnh sửa để đưa vào tài liệu với dữ liệu. - Máy chủ web gửi phản hồi HTTP. Một số phương thức
documents.batchUpdate
cung cấp nội dung phản hồi chứa thông tin về các yêu cầu được áp dụng, trong khi người khác đưa ra một câu trả lời trống.
Quy trình cập nhật tài liệu
Việc cập nhật tài liệu hiện có sẽ phức tạp hơn. Trước khi bạn có thể tạo nên ý nghĩa lệnh gọi để cập nhật tài liệu, bạn phải biết trạng thái hiện tại của tài liệu đó: các phần tử tạo nội dung, nội dung có trong các phần tử đó và thứ tự của các phần tử trong tài liệu. Sơ đồ trình tự sau đây minh hoạ cách hoạt động của chế độ này:
Trong Hình 2, người dùng tương tác với tài nguyên documents
có
luồng thông tin sau:
- Một ứng dụng gọi hàm
Phương thức
documents.get
trên web máy chủ của bạn bằngdocumentId
của tệp cần tìm. - Máy chủ web gửi phản hồi HTTP có chứa một phiên bản của
tài liệu được chỉ định dưới dạng tài nguyên
documents
. JSON được trả về chứa nội dung tài liệu, định dạng và các tính năng khác. - Ứng dụng phân tích cú pháp JSON để người dùng có thể xác định nội dung hoặc định dạng cần cập nhật.
- Ứng dụng gọi phương thức
documents.batchUpdate
để thực hiện từng tập hợp một tập hợp yêu cầu chỉnh sửa để cập nhật tài liệu. - Máy chủ web gửi phản hồi HTTP. Một số phương thức
documents.batchUpdate
cung cấp nội dung phản hồi chứa thông tin về các yêu cầu được áp dụng, trong khi người khác đưa ra câu trả lời trống.
Sơ đồ này không xem xét các quy trình công việc trong đó các bản cập nhật đồng thời của các cộng tác viên được tạo trong cùng một tài liệu. Để biết thêm thông tin, hãy xem phần thực hành Lập kế hoạch cho cộng tác.
Chủ đề có liên quan
- Cấu trúc của một tài liệu trên Google Tài liệu
- Yêu cầu và phản hồi
- Các quy tắc và hành vi chỉnh sửa cấu trúc
- Các phương pháp hay nhất để có kết quả tốt nhất