本指南包含使用 Google Drive API 管理共用雲端硬碟的相關工作,例如建立共用雲端硬碟,以及管理成員和權限。
如要指定要在回應中傳回的欄位,可以使用 drives 資源的任何方法,設定 fields system 參數。如未指定 fields 參數,伺服器會傳回方法專屬的一組預設欄位。舉例來說,list 方法只會傳回每個共用雲端硬碟的 kind、id 和 name 欄位。詳情請參閱「傳回特定欄位」。
如要進一步瞭解共用雲端硬碟資料夾限制,請參閱「共用雲端硬碟資料夾限制」。
建立共用雲端硬碟
如要建立共用雲端硬碟,請使用 drives 資源的 create 方法搭配 requestId 參數。
requestId 參數會識別共用雲端硬碟的邏輯嘗試,以進行等冪建立作業。如果要求逾時或傳回不確定的後端錯誤,可以重複發出相同要求,不會建立重複項目。要求requestId和主體必須保持不變。
以下程式碼範例說明如何建立共用雲端硬碟:
Java
Python
Node.js
PHP
.NET
對 create 方法的呼叫是冪等。
如果共用雲端硬碟是透過先前的要求或重試建立成功,這個方法會傳回 drives 資源的執行個體。有時,例如經過一段時間後,或要求主體已變更,可能會傳回 409 錯誤,指出必須捨棄 requestId。
取得共用雲端硬碟
如要取得共用雲端硬碟的中繼資料,請在 drives 資源上使用 get 方法,並搭配 driveId 路徑參數。如果您不知道雲端硬碟 ID,可以使用 list 方法列出所有共用雲端硬碟。
get 方法會以 drives 資源的執行個體形式傳回共用雲端硬碟。
如要以網域管理員身分發出要求,請將 useDomainAdminAccess 查詢參數設為 true。詳情請參閱「以網域管理員身分管理共用雲端硬碟」。
列出共用雲端硬碟
如要列出使用者的共用雲端硬碟,請使用 drives 資源的 list 方法。這個方法會傳回共用雲端硬碟清單。
傳遞下列查詢參數,即可自訂共用雲端硬碟的分頁或篩選條件:
pageSize:每個頁面傳回的共用雲端硬碟數量上限。pageToken:屬於接收自前一個清單呼叫的網頁權杖。提供此權杖即可擷取後續網頁。q:用於搜尋共用雲端硬碟的查詢字串。詳情請參閱「搜尋共用雲端硬碟」。useDomainAdminAccess:設為true,即可將要求發給網域管理員,傳回要求者所屬網域的所有共用雲端硬碟。詳情請參閱「以網域管理員身分管理共用雲端硬碟」。
更新共用雲端硬碟
如要更新共用雲端硬碟的中繼資料,請在 drives 資源上使用 update 方法,並提供 driveId 路徑參數。
這個方法會以 drives 資源的執行個體形式傳回共用雲端硬碟。
如要以網域管理員身分發出要求,請將 useDomainAdminAccess 查詢參數設為 true。詳情請參閱「以網域管理員身分管理共用雲端硬碟」。
隱藏及取消隱藏共用雲端硬碟
如要從預設檢視畫面隱藏共用雲端硬碟,請在 drives 資源上使用 hide 方法和 driveId 參數。
隱藏共用雲端硬碟後,雲端硬碟會將共用雲端硬碟資源標示為 hidden=true。隱藏的共用雲端硬碟不會顯示在雲端硬碟使用者介面或傳回的檔案清單中。
如要將共用雲端硬碟還原為預設檢視畫面,請在 drives 資源上使用 driveId 參數的 unhide 方法。
這兩種方法都會以 drives 資源例項的形式傳回共用雲端硬碟。
刪除共用雲端硬碟
如要永久刪除共用雲端硬碟,請在 drives 資源上使用 delete 方法,並搭配 driveId 參數。
刪除共用雲端硬碟前,必須先將所有內容移至垃圾桶或刪除。使用者也必須對共用雲端硬碟資料夾擁有 role=organizer。詳情請參閱「將檔案和資料夾移至垃圾桶或刪除」。
傳遞下列查詢參數,篩選共用雲端硬碟:
useDomainAdminAccess:設為true,即可將要求發給網域管理員,傳回要求者所屬網域的所有共用雲端硬碟。詳情請參閱「以網域管理員身分管理共用雲端硬碟」。allowItemDeletion:設為true可刪除共用雲端硬碟中的項目。 只有在useDomainAdminAccess也設為true時,系統才會支援這項功能。
新增或移除共用雲端硬碟成員
使用 permissions 資源新增或移除共用雲端硬碟成員。
如要新增成員,請在共用雲端硬碟中建立權限。您也可以對共用雲端硬碟中的個別檔案使用權限方法,授予成員額外權限,或允許非成員協作處理特定項目。
如需更多資訊和範例程式碼,請參閱「共用檔案、資料夾和雲端硬碟」。
以網域管理員身分管理共用雲端硬碟
搭配 drives 和 permissions 資源套用 useDomainAdminAccess 參數,即可管理整個機構的共用雲端硬碟。
使用 useDomainAdminAccess=true 呼叫這些方法的使用者必須具備Drive and Docs 管理員權限。管理員可以搜尋共用雲端硬碟,或更新所屬機構擁有的共用雲端硬碟權限,無論管理員是否為特定共用雲端硬碟的成員,都能執行這些操作。
使用服務帳戶時,您可能必須使用服務帳戶模擬功能,模擬已通過驗證的管理員。 請注意,服務帳戶不屬於您的 Google Workspace 網域,與使用者帳戶不同。如果您與整個 Google Workspace 網域共用 Google Workspace 資產 (例如文件或活動),這些資產不會與服務帳戶共用。詳情請參閱服務帳戶總覽。
復原沒有主辦人的共用雲端硬碟
下列程式碼範例說明如何復原沒有主辦人的共用雲端硬碟。
Java
Python
Node.js
PHP
.NET
禁止使用者下載、列印或複製你的檔案
您可以限制使用者在共用雲端硬碟中下載、列印及複製檔案的方式。
如要判斷使用者是否可以變更主辦人對共用雲端硬碟套用的下載限制,請檢查 capabilities.canChangeDownloadRestriction 布林值欄位。如果「capabilities.canChangeDownloadRestriction」設為「true」,則可對共用雲端硬碟套用下載限制。詳情請參閱「瞭解檔案功能」。
drives 資源包含一組布林值 restrictions 欄位,用於指出是否可對共用雲端硬碟執行動作。限制適用於共用雲端硬碟或共用雲端硬碟內的項目。
您可以使用 drives.update 方法設定限制。
如要對共用雲端硬碟套用下載限制,共用雲端硬碟管理員可以使用 DownloadRestriction 物件,設定 drives 資源的 restrictions.downloadRestriction 欄位。將 restrictedForReaders 布林值欄位設為 true,表示讀者無法下載及複製檔案。將 restrictedForWriters
布林值欄位設為 true,即表示寫手無法下載及複製檔案。請注意,如果 restrictedForWriters 欄位為 true,讀者也無法下載及複製內容。同樣地,將 restrictedForWriters 設為 true,並將 restrictedForReaders 設為 false,等同於將 restrictedForWriters 和 restrictedForReaders 都設為 true。
回溯相容性
隨著 DownloadRestriction 物件的推出,restrictions.copyRequiresWriterPermission 布林值欄位的功能也已更新。
現在,將 restrictions.copyRequiresWriterPermission 設為 true 會將 DownloadRestriction 物件的 restrictedForReaders 布林值欄位更新為 true,表示讀者無法下載及複製內容。
將 copyRequiresWriterPermission 欄位設為 false,即可將 restrictedForWriters 和 restrictedForReaders 欄位更新為 false。也就是說,所有使用者的下載或複製限制設定都會移除。
控管下載、列印和複製功能的欄位
下表列出會影響下載、列印和複製功能的 drives 資源欄位:
| 欄位 | 說明 | 版本 |
|---|---|---|
capabilities.canCopy |
目前使用者是否可以複製共用雲端硬碟中的檔案。 | v2 和 v3 |
capabilities.canDownload |
目前使用者是否可以下載共用雲端硬碟中的檔案。 | v2 和 v3 |
capabilities.canChangeCopyRequiresWriterPermission |
目前使用者是否可以變更共用雲端硬碟的 copyRequiresWriterPermission 限制。 |
v2 和 v3 |
capabilities.canResetDriveRestrictions |
目前使用者是否可以將共用雲端硬碟限制重設為預設值。 | v2 和 v3 |
capabilities.canChangeDownloadRestriction |
目前使用者是否可以變更共用雲端硬碟的下載限制。 | 僅限 v3 |
restrictions.copyRequiresWriterPermission |
是否禁止讀者和加註者複製、列印或下載共用雲端硬碟中的檔案。true,系統會將共用雲端硬碟中所有檔案的同名欄位設為 true。 |
v2 和 v3 |
restrictions.downloadRestriction |
共用雲端硬碟管理員套用的下載限制。 | 僅限 v3 |
資料夾限制
共用雲端硬碟資料夾設有儲存空間上限。詳情請參閱「Google 雲端硬碟的共用雲端硬碟限制」。
項目上限
每個使用者的共用雲端硬碟最多可容納 500,000 個項目,包括檔案、資料夾和捷徑。
達到上限後,共用雲端硬碟就無法再接受項目。如要繼續接收檔案,使用者必須從共用雲端硬碟中永久刪除項目。請注意,垃圾桶中的項目會計入上限,但永久刪除的項目則不會。詳情請參閱「將檔案和資料夾移至垃圾桶或刪除」。
資料夾深度限制
共用雲端硬碟中的單一資料夾最多只能建立 100 層巢狀資料夾。 也就是說,子資料夾不能儲存在超過 99 層的資料夾中。這項限制僅適用於子資料夾。
如果嘗試新增超過 100 層的資料夾,系統會傳回 teamDriveHierarchyTooDeep HTTP 狀態碼回應。