Hướng dẫn này giải thích cách sử dụng tài nguyên revisions để quản lý các phiên bản tệp, chẳng hạn như lấy một phiên bản tệp và xuất bản một phiên bản Google Workspace. API Google Drive cũng cho phép bạn tải các bản sửa đổi xuống. Để biết thêm thông tin chi tiết về thuật ngữ sửa đổi, hãy xem bài viết Tổng quan về các thay đổi và bản sửa đổi.
Để truy cập vào nhật ký sửa đổi, người dùng phải có role là owner, organizer, fileOrganizer hoặc writer.
Để chỉ định các trường cần trả về trong phản hồi, bạn có thể đặt tham số hệ thống fields bằng bất kỳ phương thức nào của tài nguyên revisions. Nếu bạn bỏ qua tham số này, máy chủ sẽ trả về một tập hợp các trường mặc định. Ví dụ: phương thức revisions.list chỉ trả về các trường id, mimeType, kind và modifiedTime. Để trả về các trường khác, hãy xem phần Trả về các trường cụ thể.
Chỉ định các bản sửa đổi cần lưu lại để không bị xoá tự động
Google Drive tự động xoá các phiên bản cũ mà người dùng không còn quan tâm nữa.
Bạn có thể đặt phiên bản sửa đổi tệp blob thành "Giữ vĩnh viễn", tức là phiên bản sửa đổi đó không thể bị xoá tự động. Bạn có thể đặt tối đa 200 phiên bản thành "Lưu giữ vĩnh viễn" và các phiên bản này sẽ được tính vào hạn mức bộ nhớ của bạn. Bản sửa đổi đầu không bao giờ được tự động xoá.
Mọi phiên bản tệp blob (ngoại trừ phiên bản đầu) không được chỉ định là "Giữ vĩnh viễn" đều có thể bị xoá. Các bản sửa đổi có thể xoá thường được lưu giữ trong 30 ngày, nhưng có thể bị xoá sớm hơn nếu một tệp có 100 bản sửa đổi không được chỉ định là "Lưu giữ vĩnh viễn" và một bản sửa đổi mới được tải lên.
Bạn có thể đặt trường boolean keepForever của tài nguyên revisions thành true để đánh dấu những bản sửa đổi mà bạn không muốn Drive xoá. Sau khi được đặt thành "Giữ lại vĩnh viễn", bạn chỉ có thể tải xuống hoặc xoá bản sửa đổi tệp blob. Để biết thêm thông tin, hãy xem phần Tải một bản sửa đổi xuống hoặc Xoá một bản sửa đổi.
Nếu bạn đang sử dụng Drive API phiên bản 2 cũ, hãy sử dụng trường pinned của tài nguyên revisions thay vì keepForever.
Lấy một phiên bản tệp
Để lấy siêu dữ liệu hoặc nội dung của một phiên bản tệp, hãy sử dụng phương thức get trên tài nguyên revisions bằng các tham số đường dẫn fileId và revisionId. Nếu không biết mã nhận dạng phiên bản, bạn có thể liệt kê tất cả các phiên bản của một tệp bằng phương thức list.
Phương thức này trả về siêu dữ liệu của bản sửa đổi dưới dạng một thực thể của tài nguyên revisions.
Để xác nhận rủi ro khi tải phần mềm độc hại đã biết hoặc các tệp có hành vi sai trái khác xuống, hãy đặt tham số truy vấn acknowledgeAbuse thành true. Trường này chỉ áp dụng khi bạn đặt tham số alt=media và người dùng là chủ sở hữu tệp hoặc người tổ chức của bộ nhớ dùng chung chứa tệp đó.
Liệt kê các bản sửa đổi của một tệp
Để liệt kê các phiên bản của một tệp, hãy sử dụng phương thức list trên tài nguyên revisions bằng tham số đường dẫn fileId. Phương thức này trả về danh sách các bản sửa đổi tệp.
Truyền các tham số truy vấn sau để tuỳ chỉnh việc phân trang hoặc lọc các bản sửa đổi:
pageSize: Số lượng bản sửa đổi tối đa cần trả về cho mỗi trang.pageToken: Mã thông báo trang, nhận được từ một lệnh gọi danh sách trước đó. Cung cấp mã thông báo này để truy xuất trang tiếp theo.
Cập nhật phiên bản tệp
Để cập nhật một bản sửa đổi trên tệp, hãy sử dụng phương thức update trên tài nguyên revisions bằng các tham số đường dẫn fileId và revisionId.
Phương thức này trả về một thực thể của tài nguyên revisions.
Tải bản sửa đổi xuống
Bạn chỉ có thể tải các bản sửa đổi nội dung tệp blob được đánh dấu là "Giữ vĩnh viễn" xuống. Nếu bạn muốn tải một bản sửa đổi xuống, hãy nhớ đặt bản sửa đổi đó thành "Giữ vĩnh viễn" trước. Để biết thêm thông tin, hãy xem phần Chỉ định phiên bản cần lưu để không bị xoá tự động.
Để tải nội dung của tệp blob xuống hoặc xuất nội dung của tài liệu trên Google Workspace, hãy xem phần Tải xuống và xuất tệp.
Xoá một phiên bản của tệp
Để xoá vĩnh viễn một phiên bản tệp, hãy dùng phương thức delete trên tài nguyên revisions bằng các tham số đường dẫn fileId và revisionId.
Bạn chỉ có thể xoá các bản sửa đổi của tệp blob có nội dung nhị phân trong Drive, chẳng hạn như hình ảnh, video và PDF. Bạn có thể xoá một bản sửa đổi tệp blob khi bản sửa đổi đó được đánh dấu là "Giữ vĩnh viễn". Bạn không thể xoá các bản sửa đổi của những tệp khác, chẳng hạn như tệp Google Tài liệu hoặc Trang tính, cũng như bản sửa đổi cuối cùng còn lại của tệp nhị phân.
Xuất bản bản sửa đổi
Để xuất bản một bản sửa đổi của Google Tài liệu, Google Trang tính và Google Trang trình bày, hãy đặt thuộc tính published cho tệp đó trong tài nguyên revisions. Bạn không thể đặt thuộc tính này cho các bản sửa đổi của Google Sites bằng Drive API.
Các bản sửa đổi đã xuất bản không phản ánh những thay đổi đối với một tệp, trừ phi bạn đặt thuộc tính publishAuto. Nếu bạn đặt thuộc tính này thành true, các bản sửa đổi mới hơn của một tệp sẽ tự động được xuất bản, ghi đè các bản sửa đổi trước đó.
Slides và Drawings chỉ hỗ trợ tính năng tự động xuất bản lại và yêu cầu bạn đặt thuộc tính publishAuto thành true. Đối với tệp Sites, publishAuto luôn là false.
Nếu tệp được tạo trong một miền Google Workspace, thì thuộc tính publishedOutsideDomain sẽ cho biết liệu mọi người có thể truy cập vào bản sửa đổi hay không, hoặc liệu bản sửa đổi đó có bị hạn chế đối với người dùng trong miền hay không. Đối với tệp Sites, thuộc tính này cho biết liệu có quyền type=anyone hay không. Để biết thêm thông tin, hãy xem trường type trên tài nguyên permissions.
Tính năng xuất bản tự động cũng được kiểm soát bằng hộp đánh dấu "Tự động công bố lại khi có thay đổi" trong giao diện người dùng của Tài liệu và Trang tính. Để biết thêm thông tin, hãy xem bài viết Đặt tệp Google Tài liệu, Trang tính, Trang trình bày và Biểu mẫu ở chế độ công khai.