管理檔案修訂版本

本指南說明如何使用 revisions 資源管理檔案修訂版本，例如取得檔案修訂版本，以及發布 Google Workspace 修訂版本。Google Drive API 也可讓您下載修訂版本。如要進一步瞭解修訂版本術語，請參閱變更和修訂版本總覽。

如要存取修訂版本記錄，使用者必須具備 owner、organizer、fileOrganizer 或 writer 的 role。

如要指定要在回應中傳回的欄位，您可以使用 revisions 資源的任何方法，設定 fields 系統參數。如果省略這個參數，伺服器會傳回一組預設欄位。舉例來說，revisions.list 方法只會傳回 id、mimeType、kind 和 modifiedTime 欄位。如要傳回其他欄位，請參閱「傳回特定欄位」。

指定要從自動刪除中排除的修訂版本

Google 雲端硬碟會自動刪除使用者不再需要的舊版修訂內容。

Blob 檔案修訂版本可以設為「永久保留」，也就是說，系統不會自動清除該修訂版本。最多可將 200 個修訂版本設為「永久保留」，這些版本會計入儲存空間上限。系統絕不會自動清除主要修訂版本。

除了主要修訂版本外，任何未指定為「永久保留」的 Blob 檔案修訂版本都可以清除。可清除的修訂版本通常會保留 30 天，但如果檔案有 100 個未指定為「永久保留」的修訂版本，且上傳了新的修訂版本，系統就會提早清除。

您可以將 revisions 資源的布林值 keepForever 欄位設為 true，標示不想讓雲端硬碟清除的版本。將 Blob 檔案修訂版本設為「永久保留」後，就只能下載或刪除該版本。詳情請參閱「下載修訂版本」或「刪除修訂版本」。

如果您使用的是舊版 Drive API 第 2 版，請使用 revisions 資源的 pinned 欄位，而非 keepForever。

取得檔案修訂版本

如要取得檔案修訂版本的內容或中繼資料，請使用 revisions 資源的 get 方法，並搭配 fileId 和 revisionId 路徑參數。如果您不知道修訂版本 ID，可以使用 list 方法列出檔案的所有修訂版本。

這個方法會以 revisions 資源的執行個體形式，傳回修訂版本的中繼資料。

如要確認下載已知惡意軟體或其他濫用檔案的風險，請將 acknowledgeAbuse 查詢參數設為 true。只有在設定 alt=media 參數，且使用者是檔案擁有者，或檔案所在共用雲端硬碟的召集人時，這個欄位才適用。

列出檔案的修訂版本

如要列出檔案的修訂版本，請使用 revisions 資源的 list 方法，並搭配 fileId 路徑參數。這個方法會傳回檔案修訂版本清單。

傳遞下列查詢參數，即可自訂修訂版本的頁面分頁或篩選條件：

  • pageSize：每個頁面傳回的修訂版本數量上限。

  • pageToken：屬於接收自前一個清單呼叫的網頁權杖。提供此權杖即可擷取後續網頁。

更新檔案修訂版本

如要更新檔案的修訂版本，請使用 revisions 資源的 update 方法，並搭配 fileId 和 revisionId 路徑參數。

這個方法會傳回 revisions 資源的執行個體。

下載修訂版本

您只能下載標示為「永久保存」的 Blob 檔案內容修訂版本。如要下載修訂版本，請務必先將其設為「永久保留」。詳情請參閱「指定要從自動刪除作業中儲存的修訂版本」。

如要下載 Blob 檔案內容修訂版本，或匯出 Google Workspace 文件內容修訂版本，請參閱「下載及匯出檔案」。

刪除檔案修訂版本

如要永久刪除檔案修訂版本，請在 revisions 資源上使用 delete 方法，並提供 fileId 和 revisionId 路徑參數。

您只能刪除雲端硬碟中含有二進位內容的 blob 檔案修訂版本，例如圖片、影片和 PDF。如果 Blob 檔案修訂版本標示為「永久保留」，其他檔案 (例如 Google 文件或試算表) 的修訂版本，以及二進位檔案的最後一個修訂版本，都無法刪除。

發布修訂版本

如要發布 Google 文件、Google 試算表和 Google 簡報的修訂版本，請在 revisions 資源中為該檔案設定 published 屬性。使用 Drive API 時，無法為 Google 協作平台修訂版本設定這項屬性。

除非設定 publishAuto 屬性，否則發布的修訂版本不會反映檔案變更。如果屬性設為 true，系統會自動發布檔案的新修訂版本，並覆寫舊版本。簡報和繪圖只支援自動重新發布，且必須將 publishAuto 屬性設為 true。如果是協作平台檔案，publishAuto 一律為 false。

如果檔案是在 Google Workspace 網域中建立，則 publishedOutsideDomain 屬性會指出修訂版本是否可供所有人存取，或僅限網域使用者存取。如果是 Google 協作平台檔案，這項屬性會指出是否存在 type=anyone 權限。詳情請參閱 permissions 資源的 type 欄位。

此外，您也可以在 Google 文件和試算表的 UI 中，透過「內容有所變更時自動重新發布」核取方塊，控管自動發布功能。詳情請參閱「公開 Google 文件、試算表、簡報和表單」。