每個 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。
無法從共用雲端硬碟中的檔案或資料夾移除沿用的權限。 而是必須在直接或間接父項中調整權限。您可以從「我的雲端硬碟」或「與我共用」中的項目移除沿用權限。
反之,您可以在「我的雲端硬碟」中的檔案或資料夾上覆寫沿用權限。因此,如果檔案從「我的雲端硬碟」資料夾繼承 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
{
  "requests": [
    {
        "role": "writer"
    }
  ]
}回應
{
  "kind": "drive#permission",
  "id": "PERMISSION_ID",
  "type": "user",
  "role": "writer"
}判斷角色來源
如要變更檔案或資料夾的角色,您必須知道角色的來源。如果是共用雲端硬碟,角色的來源可能是共用雲端硬碟的成員資格、資料夾的角色或檔案的角色。
如要判斷共用雲端硬碟或該硬碟中項目的角色來源,請使用  和  路徑參數,以及設為  欄位的  參數,在 permissions 資源上呼叫 get 方法。fileIdpermissionIdfieldspermissionDetails
如要找出 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 路徑參數設為刪除權限。
如果是「我的雲端硬碟」中的項目,您可以刪除繼承的權限。刪除沿用權限會撤銷項目和子項目 (如有) 的存取權。
共用雲端硬碟中的項目無法撤銷沿用權限。請改為更新或刪除上層檔案/資料夾的權限。
delete 方法也可用於刪除直接套用至共用雲端硬碟檔案或資料夾的權限。
下列程式碼範例說明如何刪除 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角色才能為資料夾設定存取權到期日。
如要進一步瞭解有效期限,請參閱下列文章: