本指南包含使用 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 狀態碼回應。