每個 Google 雲端硬碟檔案、資料夾和共用雲端硬碟都有相關聯的permissions資源。每個資源都會識別特定type (user、group、domain、anyone) 和role (owner、organizer、fileOrganizer、writer、commenter、reader) 的權限。舉例來說,某個檔案可能具有一項權限,可授予特定使用者 (type=user) 唯讀存取權 (role=reader),而另一項權限則可授予特定群組 (type=group) 的成員在檔案中新增註解的權限 (role=commenter)。
如需角色完整清單和各角色允許的作業,請參閱「角色和權限」。
權限的傳播方式
權限會從上層資料夾向下傳播至所有子項:
- 預設為沿用:所有子檔案和子資料夾都會自動沿用上層資料夾的權限。
- 無法減少子項目的權限:您無法移除或減少子項目的沿用權限。變更必須在上層資料夾進行,或是資料夾必須使用存取限制設定。
- 可擴展至子項:子項可授予較寬鬆的角色,例如在使用者擁有
role=reader的資料夾中,授予檔案role=writer。 - 移動時重新評估:將項目移至新的上層資料夾時,系統會重新評估並將新上層資料夾的權限套用至該項目及其子項。
檔案連結和存取控管
與特定使用者或群組共用檔案或資料夾時,存取項目的網址不會變更,系統也不會為每位使用者產生專屬連結。而是根據 fileId 產生單一固定連結。
Google 雲端硬碟會評估項目的 ACL,藉此控管存取權。使用者嘗試開啟連結時,雲端硬碟會根據存取控制清單 (ACL) 驗證已通過驗證的身分。如果權限遭到撤銷或到期,系統會將使用者從 ACL 中移除。如果使用者再次嘗試造訪連結,雲端硬碟會拒絕存取。
瞭解檔案功能
permissions 資源會定義「誰」有存取權 (存取控制清單),但不會直接指出目前使用者是否能在應用程式的 UI 中執行特定動作。
而是包含布林值 capabilities 欄位 (例如 canComment、canShare 或 canDelete) 的集合,Google Drive API 會根據使用者的角色和項目設定動態計算這些欄位。files 資源
取得檔案功能
在算繪應用程式的 UI 時,請檢查 files.capabilities,而不是直接剖析權限:
- 使用
fields=capabilities呼叫files.get方法。詳情請參閱「傳回特定欄位」。 - 使用傳回的布林值標記,在介面中啟用或停用對應的動作。舉例來說,如果
canComment是false,則停用留言功能。
共用雲端硬碟資源的適用情境
下表列出在不同位置和項目類型之間共用雲端硬碟資源時,所需的角色和條件:
| 位置 | 項目 | 必要的角色 | 主要限制 |
|---|---|---|---|
| 我的雲端硬碟 | 檔案或資料夾 | owner 或 writer |
ownerwritersCanShare=false如要設定資料夾的限期存取,必須具備 reader 權限 (請參閱「設定到期日」一文)。 |
| 共用雲端硬碟 | 檔案 | organizer、fileOrganizer 或 writer |
writersCanShare 一律會視為 true。 |
| 共用雲端硬碟 | 資料夾 | organizer |
如果 sharingFoldersRequiresOrganizerPermission 為 false,fileOrganizer 也可以分享。 |
| 共用雲端硬碟 | 會員制 | organizer |
僅適用於 user 或 group (不適用於網域)。 |
管理權限
下表列出 permissions 資源可用的方法:
| 方法 | API 端點 | 重要參數 | 參考資料 |
|---|---|---|---|
| 建立 | POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
role、type、emailAddress或domain |
permissions.create |
| 取得 | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
fields |
permissions.get |
| 清單 | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
pageSize、supportsAllDrives、pageToken |
permissions.list |
| 更新 | PATCH https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
role、allowFileDiscovery |
permissions.update |
| 刪除 | DELETE https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
supportsAllDrives |
permissions.delete |
建立權限
如要共用檔案、資料夾或共用雲端硬碟,請對 permissions 資源呼叫 create 方法,並使用 fileId。建立權限會在項目中新增 ACL 項目,並傳回指派的 permissionId。
在要求主體中提供下列欄位:
role:要授予的存取層級 (例如reader、commenter或writer)。如需完整清單,請參閱「角色和權限」。type:受讓人範圍 (user、group、domain或anyone)。- 受讓人 ID (視
type而定):emailAddress:type為user或group時為必要屬性。domain:type為domain時為必填。
以下程式碼範例說明如何建立權限。回應會傳回 permissions 資源的執行個體,包括指派的 permissionId。
要求
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "role": "commenter", "type": "user", "emailAddress": "alex@altostrat.com" }
回應
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}與目標對象分享
目標對象是一種使用者群組 (例如部門或團隊),您可以建議使用者在共用項目時挑選這類群組。您可以鼓勵使用者與特定或部分目標對象 (而非整個機構) 共用項目。目標對象可協助您提升資料安全性和隱私,並讓使用者更輕鬆地適當共用資料。
如要與目標對象共用,請設定 type=domain 並將 domain 設為 <TARGET_AUDIENCE_ID>.audience.googledomains.com。如要瞭解如何在 Google 管理控制台中尋找或建立目標對象,請參閱「關於目標對象」。
如要瞭解使用者與目標對象的互動情形,請參閱連結分享的使用者體驗。
取得權限
如要取得權限,請使用 fileId 和 permissionId 路徑參數,呼叫 permissions 資源的 get 方法。如果您不知道權限 ID,請先列出所有權限。
列出權限
如要列出檔案、資料夾或共用雲端硬碟的權限,請使用必要的 fileId 路徑參數,對 permissions 資源呼叫 list 方法。
您可以加入下列任一選用查詢參數,分頁或篩選回應:
pageSize(選用):每頁要傳回的權限數量上限。 如果未針對共用雲端硬碟中的檔案設定,最多會傳回 100 個結果。如果未針對不在共用雲端硬碟中的檔案設定,系統會傳回整個清單。pageToken(選用):先前 list 呼叫傳來的頁面符記,用於擷取後續頁面。supportsAllDrives(選用):要求存取權的應用程式是否同時支援「我的雲端硬碟」和共用雲端硬碟。useDomainAdminAccess(選用):設為true,以網域管理員身分發出要求。如果fileId參數參照共用雲端硬碟,且要求者是共用雲端硬碟所屬網域的管理員,系統就會授予要求者存取權。詳情請參閱「以網域管理員身分管理共用雲端硬碟」。includePermissionsForView(選用):要在回覆中加入的其他檢視權限。僅支援published。fields(選用):要在回應中傳回的特定欄位。根據預設,list只會傳回id、type、kind和role。如要傳回其他欄位 (例如permissionDetails),請使用這個參數指定。詳情請參閱「傳回特定欄位」。
判斷角色來源
如要變更檔案或資料夾的角色,您必須知道角色的來源。 如果是共用雲端硬碟,角色的來源可能是共用雲端硬碟的成員資格、資料夾的角色或檔案的角色。
如要判斷共用雲端硬碟或該硬碟中項目的角色來源,請使用 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
}
]
}更新權限
如要更新檔案或資料夾的權限,可以變更指派的角色。如要進一步瞭解如何找出角色來源,請參閱「判斷角色來源」。
在
permissions資源上呼叫update方法,並將fileId路徑參數設為相關聯的檔案、資料夾或共用雲端硬碟,以及將permissionId路徑參數設為要變更的權限。如要尋找permissionId,請使用permissions資源的list方法和fileId路徑參數。在要求中,找出新的
role。
即使使用者或群組已是成員,您還是可以授予共用雲端硬碟中個別檔案或資料夾的權限。舉例來說,假設 Alex 是共用雲端硬碟的成員,role=commenter
不過,您的應用程式可以授予 Alex
role=writer 共用雲端硬碟中檔案的存取權。在本例中,由於新角色比透過成員資格授予的角色權限更寬鬆,因此新權限會成為檔案或資料夾的有效角色。
您可以透過修補程式語意套用更新,也就是對資源進行部分修改。您必須在要求中明確設定要修改的欄位。要求中未包含的欄位會保留現有值。詳情請參閱「處理部分資源」。
除了變更角色,當權限為 type 時,您也可以修改項目的可探索性。domainanyone如要讓共用檔案可供搜尋或不列出,請在修補程式要求中加入 allowFileDiscovery 布林值欄位。設為 true 後,即使指定目標對象未取得直接連結,項目仍會顯示在搜尋結果中。您不需要刪除並重新建立權限,即可變更這項設定。
下列程式碼範例說明如何將檔案或資料夾的權限從 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"
}使用批次要求更新多項權限
系統不支援對相同檔案、資料夾或共用雲端硬碟同時進行權限修改。無論您是修改同一位或不同收件者的權限,以及要求是來自單一應用程式或多位使用者,所有變更作業 (例如更新或刪除) 都會受到這項限制。
雲端硬碟會評估並更新項目的權限,做為單一 ACL。同時進行作業會導致競爭狀況,也就是「最後寫入者勝出」,這可能會無聲無息地覆寫權限變更,或觸發 sharingRateLimitExceeded 錯誤。
為避免衝突,請依序對同一項目執行權限變更,或使用批次要求,在單一要求中修改多項權限。
以下範例說明如何使用用戶端程式庫,以批次方式修改權限。
Java
Python
Node.js
PHP
.NET
刪除權限
如要撤銷檔案或資料夾的存取權,請使用 fileId 和 permissionId 路徑參數,呼叫 permissions 資源的 delete 方法。
您無法直接撤銷子項目的沿用權限,請改為更新或刪除上層資料夾的權限 (或使用存取限制設定)。
請注意,從上層項目移除使用者的存取權,只會撤銷從該上層項目繼承的權限。如果使用者也獲得子項目的直接權限,則該直接存取權會保留。如要確認權限已移除,請使用 fileId 呼叫 list。
設定到期日
如要授予檔案或資料夾的臨時存取權,請在呼叫 create 或 update 方法時,設定 expirationTime 欄位 (RFC 3339 日期時間)。
有效期限有下列限制:
- 只能針對
user和group權限設定,不能針對domain或anyone權限設定。 - 時間必須設在未來,最長為一年。
- 如果是資料夾,只有
reader角色才能取得臨時存取權。