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 làm việc khi 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 mà bạn sử 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 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 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 documentId làm tham số để chỉ định tài liệu mục tiêu. Phương thức documents.create sẽ trả về một thực thể 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 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ể được lấy từ URL của tài liệu. Đây 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 luôn ổ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 để trích xuất documentId từ mộ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ù API Tài liệu có các phương thức độc lập riêng, nhưng bạn 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 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ó nhiều lựa chọn để lưu tệp vào 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 tệp Tài liệu

Để truy xuất mộ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 thường phải 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ó 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 các tệp Tài liệu theo loại MIME 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 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 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 của tài liệu 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 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à Docs cũng như dữ liệu được trả về theo 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 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 tệp. Lấy danh sách tệp người dùng khi bạn không chắc 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 đã 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ó nào cần 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 khái niệm, cách này hoạt động như trong sơ đồ trình tự sau:

Quy trình công việc để tạo và điền sẵn tài liệu mới.
Hình 1. Quy trình công việc để 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ó luồng thông tin sau:

  1. Ứng dụng gọi phương thức documents.create trên máy chủ web.
  2. 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 đã tạo dưới dạng tài nguyên documents.
  3. Ứ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.
  4. 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 có thông tin về các yêu cầu đã á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ó 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 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:

Quy trình làm việc để cập nhậ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:

  1. Ứ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.
  2. 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.
  3. Ứ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.
  4. Ứ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 một cách nguyên tử nhằm cập nhật tài liệu.
  5. 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 có thông tin về các yêu cầu đã á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 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 Lên kế hoạch cộng tác trong phần các phương pháp hay nhất.