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 một tài liệu đã chỉ định.
Sử dụng phương thức documents.batchUpdate để thực hiện từng bước 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 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 thực thể của tài liệu đã tạo để bạn có thể đọc documentId từ đó. Để biết thêm thông tin về các yêu cầu và phương thức phản hồi 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ể lấy từ URL của tài liệu. Đó là một chuỗi cụ thể chứa các 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ừ URL Google Tài liệu:

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

Nếu bạn đã quen thuộc với API Google Drive, thì documentId sẽ tương ứng với id trong tài nguyên files.

Quản lý tài liệu trong Google Drive

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 sử dụng các phương thức API Google Drive để tương tác với 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 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 một tài liệu hiện có.

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 thư mục Drive. Để biết thêm thông tin, hãy xem phần Làm việc với thư mục 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, trước tiên, bạn cần sử dụng phương thức files.list của Drive để truy xuất mã nhận dạng của tệp. Việc gọi phương thức mà không có bất kỳ tham số nào 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 kiểu dữ liệu và định dạng. Đị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 phần 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 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.

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 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à xuất đúng loại MIME. Để 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 các 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ề qua 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 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 đã 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 vào tài liệu mới rất đơn giản, vì hiện 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 biểu đồ trình tự sau đây:

Quy trình tạo và
điền sẵn tài liệu mới. — **Hình 1.** Quy trình tạo và điền sẵn 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 sẽ 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 một 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 loạt 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 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 một số phương thức khác 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ó sẽ 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: những phần tử tạo nên tài liệu, 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:

Quy trình cập nhật một tài liệu. — **Hình 2.** Quy trình cập nhật tài liệu.

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 bằng documentId của tệp cần tìm.
Máy chủ web gửi một phản hồi HTTP có chứa một thực thể 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 một tập hợp các yêu cầu chỉnh sửa ở dạng tỷ lệ cho việc 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 một số phương thức khác hiển thị phản hồi trống.

Sơ đồ này không xem xét các quy trình công việc trong đó các cộng tác viên khác thực hiện đồ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ên kế hoạch cộng tác.