Trang này được dịch bởi Cloud Translation API.

Tài liệu

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 vào tài liệu và quy trình tạo tài liệu.

Phương thức API

Tài nguyên documents cung cấp các phương thức bạn dùng để gọi API Tài liệu. 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 Tài liệu:

Sử dụng phương thức 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 tài liệu được chỉ định.
Sử dụng phương thức documents.batchUpdate để thực hiện nhiều nội dung cập nhật trên một tài liệu được chỉ định.

Phương thức documents.get và documents.batchUpdate yêu cầu documentId làm tham số để chỉ định tài liệu mục tiêu. Phương thức documents.create trả về một bản sao của tài liệu đã tạo, từ đó bạn có thể đọc documentId. Để biết thêm thông tin về các phương thức phản hồi và yêu cầu của API Tài liệu, hãy xem phần Yêu cầu và phản hồi.

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ể được lấy từ URL của 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 ổn định, ngay cả khi tên tài liệu thay đổi.

https://docs.google.com/document/d/DOCUMENT_ID/edit

Bạn có thể sử dụng biểu thức chính quy sau đây để trích xuất documentId từ URL trên Google Tài liệu:

/document/d/([a-zA-Z0-9-_]+)

Nếu bạn đã quen thuộc với API Google Drive, documentId sẽ 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ữ 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 thông thường, bạn cũng cần 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 các tệp Tài liệu, hãy sử dụng phương thức files.copy của API Drive. Để biết thêm thông tin, hãy xem phần Sao chép tài liệu hiện có.

Theo mặc định, khi sử dụng API Tài liệu, 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 tuỳ chọn để lưu tệp vào thư mục Drive. Để biết thêm thông tin, hãy xem phần Thao tác với thư mục Google Drive.

Thao tác với các tệp Tài liệu

Để truy xuất tài liệu từ Drive của tôi của người dùng, trước tiên, thường bạn cần sử dụng phương thức files.list của Drive để truy xuất mã nhận dạng cho một tệp. Việc gọi phương thức mà không có tham số sẽ trả về danh sách tất cả cá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 các loại MIME được Google Workspace và Google Drive hỗ trợ.

Để tìm kiếm theo loại MIME chỉ đối với các tệp Tài liệu trong Drive của tôi, hãy thêm bộ lọc chuỗi truy vấn sau:

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 phần Tìm kiếm tệp và thư mục.

Khi bạn đã biết documentId, hãy sử dụng phương thức documents.get để truy xuất thực thể hoàn chỉnh của tài liệu đã chỉ định. Để biết thêm thông tin, hãy xem phần 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 sử dụng phương thức files.export của Drive với documentId của tệp để xuất và đúng loại MIME xuất. Để biết thêm thông tin, hãy xem bài viết Xuất nội dung tài liệu trên Google Workspace.

So sánh phương thức `Get` và `List`

Bảng sau đây mô tả sự khác biệt giữa phương thức Drive và Tài liệu, cũng như dữ liệu được trả về trong mỗi phương thức:

Đơn vị tổ chức	Nội dung 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 của một tệp cụ thể.
`drive.files.list`	Lấy các tệp của người dùng. Trả về danh sách các tệp.	Nhận danh sách tệp người dùng khi bạn không chắc chắn mình phải sửa đổi tệp nào.
`docs.documents.get`	Lấy 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`.	Lấy 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 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, trình tự này hoạt động như minh hoạ trong sơ đồ trình tự sau đây:

Quy trình làm việc để tạo và
điền sẵn tài liệu mới. — **Hình 1.** Quy trình làm việc để tạo và điền vào một tài liệu mới.

Trong Hình 1., 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 phương thức documents.create trên máy chủ web.
Máy chủ web gửi phản hồi HTTP chứa một bản sao 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 phương thức documents.batchUpdate để thực hiện một tập hợp các yêu cầu chỉnh sửa nhằm điền sẵn dữ liệu vào tài liệu.
Máy chủ web gửi một 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 đã áp dụng, trong khi các phương thức khác lại hiển thị phản hồ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ó 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 mộ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 thành phần tạo nên tài liệu, nội dung của các thành phần đó và thứ tự của các thành phần trong tài liệu. Sơ đồ trình tự sau đây cho thấy cách hoạt động của quá trình 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 phương thức documents.get trên máy chủ web, với documentId của tệp cần tìm.
Máy chủ web gửi một phản hồi HTTP chứa một thực thể của tài liệu đã 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 một tập hợp các yêu cầu chỉnh sửa để cập nhật tài liệu.
Máy chủ web gửi một 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 đã áp dụng, trong khi các phương thức khác lại hiển thị phản hồi trống.

Sơ đồ này không xem xét quy trình làm việc trong đó các cộng tác viên khác thực hiện cập nhật đồng thời trong cùng một tài liệu. Để biết thêm thông tin, hãy xem phần các phương pháp hay nhất Lập kế hoạch cộng tác.