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 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 giú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 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 documents.batchUpdate để thực hiện từng tập hợp cập nhật trên một tài liệu cụ thể.

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, bộ nhớ 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 việc này 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ài liệu. 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 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. Để xem 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 đã 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ơ đồ:

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 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:

Quy trình làm việc để 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 hàm Phương thức documents.get trên web máy chủ của bạn bằng documentId 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 một 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.