每個 Google 雲端硬碟檔案、資料夾和共用雲端硬碟都有相關聯的permissions資源。每個資源都會識別特定type (user、group、domain、anyone) 和role (owner、organizer、fileOrganizer、writer、commenter、reader) 的權限。舉例來說,某個檔案可能具有權限,可授予特定使用者 (type=user) 唯讀存取權 (role=reader),而另一個權限則可授予特定群組 (type=group) 的成員在檔案中新增註解的權限 (role=commenter)。
如需角色完整清單,以及各角色允許的作業,請參閱「角色和權限」一文。
權限的運作方式
資料夾的權限清單會向下傳播。所有子檔案和資料夾都會沿用上層資料夾的權限。每當權限或階層變更時,系統會透過所有巢狀資料夾以遞迴方式傳播變更。舉例來說,如果檔案位於某個資料夾中,而該資料夾隨後移至另一個資料夾,則新資料夾的權限會傳播至該檔案。如果新資料夾授予檔案使用者新角色 (例如「寫入者」),系統會覆寫舊角色。
相反地,如果檔案從資料夾繼承 role=writer,並移至提供「讀者」角色的另一個資料夾,檔案現在會繼承 role=reader。
您無法移除或降低任何項目的沿用權限。您必須在上層調整這些權限,或在階層中的資料夾啟用存取限制設定。
項目的沿用權限可以增加,如果子帳戶的權限提高,除非新的家長權限高於子帳戶,否則變更家長權限不會影響子帳戶權限。
系統不支援對同一個檔案執行並行權限作業。系統只會套用最後一次更新。
瞭解檔案功能
permissions 資源最終不會決定目前使用者對檔案或資料夾執行動作的能力。而是包含布林值 capabilities 欄位的集合,用來指出是否可對檔案或資料夾執行動作。filesGoogle Drive API 會根據與檔案或資料夾相關聯的目前使用者permissions資源,設定這些欄位。
舉例來說,當 Alex 登入您的應用程式並嘗試共用檔案時,系統會檢查 Alex 的角色是否具備該檔案的權限。如果角色允許使用者共用檔案,系統會根據角色設定檔案的相關權限,例如 capabilities 和 canShare。如果 Alex 想分享檔案,應用程式會檢查 capabilities,確保 canShare 設為 true。
取得檔案功能
應用程式開啟檔案時,應檢查檔案功能並顯示 UI,反映目前使用者的權限。舉例來說,如果使用者沒有檔案的 canComment 功能,UI 應停用加註功能。
如要檢查功能,請使用 fileId 路徑參數,並將 fields 參數設為 capabilities 欄位,對 files 資源呼叫 get 方法。如要進一步瞭解如何使用 fields 參數傳回欄位,請參閱「傳回特定欄位」。
以下程式碼範例說明如何驗證使用者權限。回應會傳回使用者對檔案擁有的功能清單。每項能力都對應至使用者可執行的細部動作。部分欄位只會填入共用雲端硬碟中的項目。
要求
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=capabilities回應
{ "capabilities": { "canAcceptOwnership": false, "canAddChildren": false, "canAddMyDriveParent": false, "canChangeCopyRequiresWriterPermission": true, "canChangeItemDownloadRestriction": true, "canChangeSecurityUpdateEnabled": false, "canChangeViewersCanCopyContent": true, "canComment": true, "canCopy": true, "canDelete": true, "canDisableInheritedPermissions": false, "canDownload": true, "canEdit": true, "canEnableInheritedPermissions": true, "canListChildren": false, "canModifyContent": true, "canModifyContentRestriction": true, "canModifyEditorContentRestriction": true, "canModifyOwnerContentRestriction": true, "canModifyLabels": true, "canMoveChildrenWithinDrive": false, "canMoveItemIntoTeamDrive": true, "canMoveItemOutOfDrive": true, "canMoveItemWithinDrive": true, "canReadLabels": true, "canReadRevisions": true, "canRemoveChildren": false, "canRemoveContentRestriction": false, "canRemoveMyDriveParent": true, "canRename": true, "canShare": true, "canTrash": true, "canUntrash": true } }
共用雲端硬碟資源的情境
分享情境分為以下五種:
如要共用「我的雲端硬碟」中的檔案,使用者必須具備
role=writer或role=owner。如果檔案的
writersCanShare布林值設為false,使用者必須具備role=owner。如果使用者具有
role=writer,且臨時存取權受限於到期日期和時間,就無法共用檔案。詳情請參閱「設定到期日,限制項目存取權」。
如要共用「我的雲端硬碟」中的資料夾,使用者必須擁有
role=writer或role=owner。如果檔案的
writersCanShare布林值設為false,使用者必須具備更寬鬆的role=owner。臨時存取權 (受存取期限和時間限制) 僅適用於含有
role=reader的資料夾。詳情請參閱「設定到期日,限制項目存取權」。
如要分享共用雲端硬碟中的檔案,使用者必須具備
role=writer、role=fileOrganizer或role=organizer權限。writersCanShare設定不適用於共用雲端硬碟中的項目。 系統會將其視為一律設為true。
如要共用共用雲端硬碟中的資料夾,使用者必須具備
role=organizer。- 如果共用雲端硬碟的
sharingFoldersRequiresOrganizerPermission限制設為false,則具有role=fileOrganizer的使用者可以共用該共用雲端硬碟中的資料夾。
- 如果共用雲端硬碟的
使用者必須具備
role=organizer,才能管理共用雲端硬碟成員。只有使用者和群組可以成為共用雲端硬碟的成員。
使用 fields 參數
如要指定要在回應中傳回的欄位,可以使用 permissions 資源的任何方法,設定 fields system 參數。如果省略 fields 參數,伺服器會傳回方法專屬的預設欄位集。舉例來說,list 方法只會傳回每個檔案的 id、type、kind 和 role 欄位。如要傳回不同欄位,請參閱「傳回特定欄位」。
建立權限
建立權限時,必須填寫下列兩個欄位:
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。
以下程式碼範例說明如何建立權限。回應會傳回 permissions 資源的執行個體,包括指派的 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 資源上使用 get 方法,並搭配 fileId 和 permissionId 路徑參數。如果您不知道權限 ID,可以使用 list 方法列出所有權限。
下列程式碼範例說明如何依 ID 取得權限。回應會傳回 permissions 資源的例項。
要求
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissionsPERMISSION_ID
回應
{
"kind": "drive#permissionList",
"permissions": [
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}
]
}列出所有權限
如要列出檔案、資料夾或共用雲端硬碟的權限,請在 permissions 資源上使用 list 方法,並搭配 fileId 路徑參數。
傳遞下列查詢參數,自訂權限的分頁功能或篩選權限:
pageSize:每頁要傳回的權限數量上限。如果未設定共用雲端硬碟中的檔案,最多會傳回 100 個結果。如果未針對非共用雲端硬碟中的檔案設定,系統會傳回完整清單。pageToken:屬於接收自前一個清單呼叫的網頁權杖。提供此權杖即可擷取後續網頁。supportsAllDrives:要求應用程式是否同時支援「我的雲端硬碟」和共用雲端硬碟。useDomainAdminAccess:設為true,以網域管理員身分發出要求。如果fileId參數參照共用雲端硬碟,且要求者是共用雲端硬碟所屬網域的管理員,詳情請參閱「以網域管理員身分管理共用雲端硬碟」。includePermissionsForView:要納入回應的其他檢視畫面權限。系統僅支援published。
下列程式碼範例說明如何取得所有權限。回應會傳回檔案、資料夾或共用雲端硬碟的權限清單。
要求
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"
}
]
}更新權限
如要更新檔案或資料夾的權限,可以變更指派的角色。如要進一步瞭解如何找出角色來源,請參閱「判斷角色來源」。
在
permissions資源上呼叫update方法,並將fileId路徑參數設為相關聯的檔案、資料夾或共用雲端硬碟,以及將permissionId路徑參數設為要變更的權限。如要找出permissionId,請使用permissions資源的list方法,並搭配fileId路徑參數。在要求中,找出新的
role。
即使使用者或群組已是成員,您還是可以授予共用雲端硬碟中個別檔案或資料夾的權限。舉例來說,Alex 是共用雲端硬碟的成員,role=commenter不過,您的應用程式可以授予 Alex
role=writer 共用雲端硬碟中檔案的權限。在這種情況下,由於新角色的權限高於透過成員資格授予的角色,因此新權限會成為檔案或資料夾的有效角色。
您可以透過修補程式語意套用更新,也就是對資源進行部分修改。您必須在要求中明確設定要修改的欄位。要求中未包含的欄位會保留現有值。詳情請參閱「處理部分資源」。
以下程式碼範例說明如何將檔案或資料夾的權限從 commenter 變更為 writer。回應會傳回 permissions 資源的例項。
要求
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"role": "writer"
}回應
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}判斷角色來源
如要變更檔案或資料夾的角色,您必須知道角色的來源。如果是共用雲端硬碟,角色的來源可能是共用雲端硬碟的成員資格、資料夾的角色或檔案的角色。
如要判斷共用雲端硬碟或該雲端硬碟中項目的角色來源,請使用 fileId 和 permissionId 路徑參數,以及設為 permissionDetails 欄位的 fields 參數,在 permissions 資源上呼叫 get 方法。
如要尋找 permissionId,請在 permissions 資源上使用 list 方法,並搭配 fileId 路徑參數。如要擷取 list 要求中的 permissionDetails 欄位,請將 fields 參數設為 permissions/permissionDetails。
這個欄位會列舉使用者、群組或網域的所有沿用和直接檔案權限。
下列程式碼範例說明如何判斷角色來源。回應會傳回 permissions 資源的 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
}
]
}使用批次要求更新多項權限
強烈建議使用批次要求修改多項權限。
以下範例說明如何使用用戶端程式庫,以批次方式修改權限。
Java
Python
Node.js
PHP
.NET
刪除權限
如要撤銷檔案或資料夾的存取權,請在 permissions 資源上呼叫 delete 方法,並將 fileId 和 permissionId 路徑參數設為刪除權限。
沿用權限無法撤銷。請改為更新或刪除上層資料夾的權限。刪除資料夾的權限時,也會一併撤銷子項目的同等存取權。
如要減少權限,請使用受限存取權設定。
請注意,從上層項目移除使用者的存取權,只會撤銷從上層項目繼承的權限。如果使用者直接獲得子檔案或子資料夾的權限,他們仍可存取這些項目。如要確保所有子項目的權限與父項目的權限一致,您必須找出並移除授予使用者這些子項目的任何直接權限。
下列程式碼範例說明如何刪除 permissionId 來撤銷存取權。如果成功,回應主體會是空白的 JSON 物件。如要確認權限已移除,請在 permissions 資源上使用 list 方法,並提供 fileId 路徑參數。
要求
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
設定到期日,限制項目存取權
與他人合作處理機密專案時,您可能希望在一段時間後限制他們存取雲端硬碟中的特定項目。您可以為檔案和資料夾設定到期日,藉此限制或移除特定人士的存取權。
如要設定到期日,請按照下列步驟操作:
在
permissions資源上使用create方法,並設定expirationTime欄位 (以及其他必要欄位)。詳情請參閱「建立權限」。在
permissions資源上使用update方法,並設定expirationTime欄位 (以及其他必要欄位)。詳情請參閱「更新權限」。
expirationTime 欄位會以 RFC 3339 日期時間格式,指出權限到期時間。到期時間有下列限制:
- 僅限對使用者和群組權限設定。
- 時間必須是未來的時間。
- 時間不得超過一年。
- 只有
reader角色才能設定資料夾的存取權到期日。
如要進一步瞭解有效期限,請參閱下列文章: