每個 Google 雲端硬碟檔案、資料夾和共用雲端硬碟都有相關聯的權限資源。每項資源都會識別特定 type
(使用者、群組、網域、任何人) 和 role
的權限,例如「加註者」或「讀取者」。例如,檔案可能具有授予特定使用者 (type=user
) 唯讀存取權 (role=reader
) 的權限,另一個權限則授予特定群組成員 (type=group
) 在檔案中加入註解的權限 (role=commenter
)。
如需角色和各權限所允許作業的完整清單,請參閱角色和權限。
共用雲端硬碟資源的情境
分享情況分為五個不同類型:
如要在「我的雲端硬碟」中共用檔案,使用者必須具備
role=writer
或role=owner
。如果檔案的
writersCanShare
布林值設為False
,使用者就必須擁有role=owner
。如果具備
role=writer
的使用者擁有臨時存取權,並受到期日和時間的規範,則無法共用檔案。詳情請參閱「設定到期日以限制檔案存取權」。
如要共用「我的雲端硬碟」中的資料夾,使用者必須具備
role=writer
或role=owner
。如果檔案的
writersCanShare
布林值設為False
,使用者就必須擁有較寬鬆的role=owner
。具有
role=writer
的「我的雲端硬碟」資料夾不允許臨時存取權 (依到期日和時間管理)。詳情請參閱「設定到期日以限制檔案存取權」。
如要在共用雲端硬碟中共用檔案,使用者必須具備
role=writer
、role=fileOrganizer
或role=organizer
。writersCanShare
設定不適用於共用雲端硬碟中的項目。 系統會將其視為一律設為True
。
如要與他人共用共用雲端硬碟中的資料夾,使用者必須具備
role=organizer
。- 如果將共用雲端硬碟的
sharingFoldersRequiresOrganizerPermission
限制設為False
,則具備role=fileOrganizer
的使用者可以在該共用雲端硬碟中共用資料夾。
- 如果將共用雲端硬碟的
使用者必須擁有
role=organizer
,才能管理共用雲端硬碟成員資格。只有使用者和群組可以成為共用雲端硬碟的成員。
設定到期日以限制檔案存取權
當您和敏感專案的使用者合作時,您可能會希望使用者在經過一段時間後限制他們對於雲端硬碟中特定檔案的存取權。您可以為「我的雲端硬碟」中的檔案設定到期日,限製或移除檔案存取權。
如何設定到期日:
- 使用
permissions.create
方法並設定permissions.expirationTime
欄位 (以及其他必填欄位)。詳情請參閱「建立權限」。 - 使用
permissions.update
方法並設定permissions.expirationTime
欄位 (以及其他必填欄位)。詳情請參閱「變更權限」。
expirationTime
欄位會使用 RFC 3339 日期時間表示權限到期時間。到期時間具有以下限制:
- 只能針對使用者和群組權限進行設定。
- 時間必須在未來。
- 時間不得超過未來一年。
如要進一步瞭解到期日,請參閱下列文章:
權限傳播
資料夾的權限清單會向下傳播,所有子項檔案和資料夾都會繼承父項的權限。每當權限或階層有所變更,所有巢狀資料夾都會以遞迴方式進行。舉例來說,如果檔案存在資料夾中,而該資料夾在另一個資料夾中移動,則新資料夾的權限會套用到該檔案。如果新資料夾授予檔案使用者新角色 (例如「寫入者」),新角色會覆寫舊角色。
相反地,如果檔案沿用資料夾的 role=writer
,並移至另一個提供「讀取者」角色的資料夾,則檔案現在會沿用 role=reader
。
您無法移除共用雲端硬碟內檔案或資料夾的繼承權限。 相反地,這些權限必須在繼承的直接或間接父項上調整。您可以將繼承的權限從「我的雲端硬碟」或「與我共用」下的項目中移除。
相反地,您可以針對「我的雲端硬碟」中的檔案或資料夾,覆寫繼承的權限。因此,如果檔案沿用「我的雲端硬碟」資料夾的 role=writer
,您可以將檔案的 role=reader
設為降低其權限等級。
功能
權限資源最終不會決定目前使用者能否對檔案或資料夾執行操作。而是「檔案」資源包含一組布林值 capabilities
欄位,用於指出是否可在檔案或資料夾上執行動作。Google Drive API 會根據目前與檔案或資料夾相關聯的使用者權限資源,設定這些欄位。
例如,當 Alex 登入您的應用程式並嘗試分享檔案時,系統會檢查 Alex 的角色是否有檔案的權限。如果角色允許他們共用檔案,系統就會根據角色填入與檔案相關的 capabilities
(例如 canShare
)。如果 Alex 想要共用檔案,應用程式會檢查 capabilities
,確保 canShare
已設為 true
。
如需擷取 capabilities
檔案的範例,請參閱「驗證使用者權限」。
建立權限
建立權限時,必須提供以下兩個欄位:
type
:type
可識別權限範圍 (user
、group
、domain
或anyone
)。具有type=user
的權限適用於特定使用者,而type=domain
權限則會套用至特定網域中的所有人。role
:role
欄位可識別type
可執行的作業。舉例來說,具備type=user
和role=reader
的權限會將檔案或資料夾的唯讀存取權授予特定使用者。或者,具有type=domain
和role=commenter
的權限可讓網域中的所有使用者在檔案中加註。如需角色和各權限所允許作業的完整清單,請參閱角色和權限。
建立 type=user
或 type=group
的權限時,您還必須提供 emailAddress
,將權限綁定特定使用者或群組。
建立 type=domain
的權限時,您也必須提供 domain
,將特定網域與權限連結。
如何建立權限:
- 將
permissions.create
方法與關聯檔案或資料夾的fileId
搭配使用。 - 在要求主體中指定
type
和role
。 - 如果值為
type=user
或type=group
,請提供emailAddress
。如果值為type=domain
,請提供domain
。
顯示範例
以下程式碼範例說明如何建立權限。回應會傳回 Permission
資源的執行個體,包括指派的 permissionId
。
要求
POST https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
{ "requests": [ { "type": "user", "role": "commenter", "emailAddress": "alex@altostrat.com" } ] }
回應
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "commenter"
}
使用目標對象
目標對像是一種使用者群組 (例如部門或團隊),您可以將這類群組當做使用者的建議共用對象。您可以鼓勵使用者與特定或部分目標對象 (而非整個機構) 共用項目。目標對象可協助您改善資料的安全性和隱私權,讓使用者更輕鬆地進行適當共用。詳情請參閱「關於目標對象」。
目標對象的使用方式如下:
在 Google 管理控制台中,依序點選「選單」圖示 >「目錄」>「目標對象」。
您必須使用具備超級管理員權限的帳戶登入,才能執行這項工作。
在「目標對象清單」中,按一下目標對象的名稱。如要建立目標對象,請參閱「建立目標對象」一文
複製目標對象網址中的專屬 ID:
https://admin.google.com/ac/targetaudiences/ID
。使用
type=domain
建立權限,然後將domain
欄位設為ID.audience.googledomains.com
。
如要查看使用者與目標對象互動的方式,請參閱「連結共用的使用者體驗」。
擷取檔案、資料夾或共用雲端硬碟的所有權限
使用 permissions.list
方法擷取檔案、資料夾或共用雲端硬碟的所有權限。
顯示範例
下列程式碼範例說明如何取得所有權限。回應會傳回權限清單。
要求
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
回應
{
"kind": "drive#permissionList",
"permissions": [
{
"id": "PERMISSION_ID
",
"type": "user",
"kind": "drive#permission",
"role": "commenter"
}
]
}
驗證使用者權限
應用程式開啟檔案時,應檢查該檔案的功能並轉譯 UI,反映目前使用者的權限。舉例來說,如果使用者檔案沒有 canComment
功能,則應在使用者介面中停用註解功能。
如要進一步瞭解 capabilities
,請參閱上方的「功能」一節。
如要檢查功能,請使用 fileId
和設為 capabilities
欄位的 fields
參數呼叫 files.get
。如要進一步瞭解如何使用 fields
參數傳回欄位,請參閱「傳回檔案的特定欄位」。
顯示範例
下列程式碼範例說明如何驗證使用者權限。回應會傳回使用者在檔案中具備的功能清單。每項功能都對應到使用者能採取的細部動作。部分欄位只會針對共用雲端硬碟中的項目填入資料。
要求
GET https://www.googleapis.com/drive/v3/files/FILE_ID
?fields=capabilities
回應
{ "capabilities": { "canAcceptOwnership": false, "canAddChildren": false, "canAddMyDriveParent": false, "canChangeCopyRequiresWriterPermission": true, "canChangeSecurityUpdateEnabled": false, "canComment": true, "canCopy": true, "canDelete": true, "canDownload": true, "canEdit": true, "canListChildren": false, "canModifyContent": true, "canModifyContentRestriction": true, "canModifyLabels": true, "canMoveChildrenWithinDrive": false, "canMoveItemOutOfDrive": true, "canMoveItemWithinDrive": true, "canReadLabels": true, "canReadRevisions": true, "canRemoveChildren": false, "canRemoveMyDriveParent": true, "canRename": true, "canShare": true, "canTrash": true, "canUntrash": true } }
判斷共用雲端硬碟檔案和資料夾的角色來源
如要變更檔案或資料夾的角色,您必須瞭解角色來源。 就共用雲端硬碟而言,角色來源可以依據共用雲端硬碟的成員資格、資料夾中的角色或檔案的角色。
如要判斷共用雲端硬碟或其中項目的角色來源,請使用 fileId
、permissionId
和設為 permissionDetails
欄位的 fields
參數呼叫 permissions.get
。如要尋找 permissionId
,請將 permissions.list
與 fileId
搭配使用。如要擷取 permissions.list
要求中的 permissionDetails
欄位,請將 fields
參數設為 permissions/permissionDetails
。
這個欄位會列舉使用者、群組或網域的所有繼承和直接檔案權限。
顯示範例
以下程式碼範例說明如何判斷角色來源。回應會傳回 Permission
資源的 permissionDetails
。inheritedFrom
欄位會提供沿用權限的項目 ID。
要求
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
?fields=permissionDetails&supportsAllDrives=true
回應
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID
",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}
變更權限
如要變更檔案或資料夾的權限,您可以變更指派的角色:
使用具備變更權限的
permissionId
和關聯檔案、資料夾或共用雲端硬碟的fileId
呼叫permissions.update
。如要尋找permissionId
,請將permissions.list
與fileId
搭配使用。在要求中,找出新的
role
。
即便使用者或群組已經是成員,您還是可以授予共用雲端硬碟中個別檔案或資料夾的權限。舉例來說,Alex 的共用雲端硬碟成員資格包含 role=commenter
。不過,您的應用程式可以將共用雲端硬碟中的檔案授予 Alex role=writer
。在此情況下,由於新角色的權限比透過成員資格授予的角色來得寬鬆,因此新權限就會成為檔案或資料夾的有效角色。
顯示範例
以下程式碼範例說明如何將檔案或資料夾的權限從加註者變更為寫入者。回應會傳回 Permission
資源的執行個體。
要求
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
{ "requests": [ { "role": "writer" } ] }
回應
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "writer"
}
撤銷檔案或資料夾的存取權
如要撤銷檔案或資料夾的存取權,請使用 fileId
和 permissionId
呼叫 delete
,以便刪除該權限。
在「我的雲端硬碟」中,您可以刪除繼承的權限。刪除沿用的權限會撤銷該項目和子項項目 (如果有的話) 的存取權。
無法撤銷共用雲端硬碟中項目的沿用權限。請改為更新或撤銷上層檔案或資料夾的權限。
delete
作業也可以用來刪除直接套用至共用雲端硬碟檔案或資料夾的權限。
顯示範例
下列程式碼範例說明如何透過刪除 permissionId
撤銷存取權。如果成功,回應主體會是空白的。如要確認移除權限,請搭配 fileId
使用 permissions.list
。
要求
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
將檔案擁有權轉移給相同機構中的其他 Google Workspace 帳戶
「我的雲端硬碟」中現有檔案的擁有權可從同一個機構中的另一個 Google Workspace 帳戶轉移至另一個帳戶。擁有共用雲端硬碟的機構 就能擁有其中檔案因此,共用雲端硬碟中的檔案和資料夾不支援擁有權轉移。共用雲端硬碟的主辦人可以將該共用雲端硬碟中的項目移至自己的「我的雲端硬碟」,而後者會將擁有權轉移給他人。
如要轉移「我的雲端硬碟」中檔案的擁有權,請執行下列其中一項操作:
建立檔案權限,授予特定使用者 (
type=user
) 擁有者存取權 (role=owner
)。使用
role=owner
更新現有檔案的權限,並將擁有權轉移給指定使用者 (transferOwnership=true
)。
在個人帳戶之間轉移檔案擁有權
檔案擁有權可在其中一個個人帳戶之間轉移。 不過,在潛在的新擁有者明確同意轉移作業之前,雲端硬碟不會在兩個個人帳戶之間轉移檔案擁有權。如要將檔案擁有權從某個個人帳戶轉移至另一個個人帳戶,請按照下列步驟操作:
目前擁有者會建立或更新潛在新擁有者的檔案權限,藉此啟動擁有權轉移程序。權限必須包含這些設定:
role=writer
、type=user
和pendingOwner=true
。如果新擁有者為潛在擁有者建立權限,系統會傳送電子郵件通知給潛在新擁有者,說明他們要求取得檔案的擁有權。新擁有者會建立或更新其檔案權限,以接受擁有權轉移要求。權限必須包含這些設定:
role=owner
和transferOwnership=true
。如果新擁有者建立新權限,系統會傳送電子郵件通知給前一位擁有者,指出已轉移擁有權。
檔案轉移後,先前的擁有者的角色會降級為 writer
。
使用批次要求變更多項權限
強烈建議您使用批次要求來修改多項權限。
以下是透過用戶端程式庫執行批次權限修改作業的範例。