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ư những phương thức chính tạo nên Google Docs API, cách truy cập vào một tài liệu và quy trình khi tạo một tài liệu.

Phương thức API

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

Sử dụng phương thức documents.create để tạo một 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 cụ thể.
Sử dụng phương thức documents.batchUpdate để thực hiện một loạt các bản 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 documentId làm tham số để chỉ định tài liệu đích. Phương thức documents.create trả về một phiên bản 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 yêu cầu và phản hồi của Docs API, hãy xem phần Yêu cầu và phản hồi.

Mã nhận dạng 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. Đây là một chuỗi cụ thể chứa chữ cái, chữ số và một số ký tự đặc biệt. Mã nhận dạng tài liệu có tính ổ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ể dùng biểu thức chính quy sau đây để trích xuất documentId 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, thì 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ù Docs API có các phương thức độc lập riêng, nhưng bạn thường cần sử dụng cả các phương thức Google Drive API để 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 phương thức files.copy của Drive API. Để 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 sử dụng Docs API, 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. Bạn có thể lưu tệp vào một thư mục trên Drive. Để biết thêm thông tin, hãy xem bài viết Làm việ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 một tài liệu từ Drive của tôi của người dùng, thường thì 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 một tệp. Khi gọi phương thức mà không có tham số nào, phương thức này 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. Để 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ợ.

Để tìm kiếm theo loại MIME chỉ 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 biết documentId, hãy dùng phương thức documents.get để truy xuất một phiên bản 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 của 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 cần xuất và loại MIME xuất chính xác. Để 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 các phương thức Drive và Tài liệu, cũng như dữ liệu được trả về với từng 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 một tệp theo mã nhận dạng. Trả về một phiên bản 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 tệp.	Lấy 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 phiên bản của tài nguyên `documents`.	Lấy tài liệu cho một mã nhận dạng tài liệu cụ thể.

Quy trình tạo tài liệu

Việc tạo và điền sẵn nội dung vào một tài liệu mới rất đơn giản, vì bạn không cần lo lắng về nội dung hiện có và không có cộng tác viên nào có thể thay đổi trạng thái của tài liệu. Về mặt khái niệm, điều này hoạt động như minh hoạ trong sơ đồ trình tự sau:

**Hình 1.** Quy trình tạo và điền sẵn thông tin vào một tài liệu mới.

Trong Hình 1, một 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ột máy chủ web.
Máy chủ web gửi một phản hồi HTTP 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.
Ngoài ra, ứng dụng có thể gọi phương thức documents.batchUpdate để thực hiện một cách nguyên tử một tập hợp các yêu cầu chỉnh sửa nhằm điề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 có thông tin về các yêu cầu đã áp dụng, trong khi những phương thức khác đưa ra một phản hồi trống.

Quy trình cập nhật tài liệu

Việc cập nhật mộ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 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 cho thấy cách hoạt động của quy trình này:

Trong Hình 2, một 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.get trên một 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 phiên bản 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, định dạng và các tính năng khác của tài liệu.
Ứng dụng này 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 nhóm yêu cầu chỉnh sửa nhằm cập nhật tài liệu một cách nhất quán.
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 có thông tin về các yêu cầu đã áp dụng, trong khi những phương thức khác đưa ra một phản hồi trống.

Sơ đồ này không xem xét những quy trình làm việc mà 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. Để 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 cho hoạt động cộng tác.