每个 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 资源最终不会
决定当前用户对文件或文件夹执行操作的能力。相反,files 资源包含一组
布尔值 capabilities
字段,用于指明是否可以对文件或文件夹执行操作。
Google Drive API 会根据当前用户与文件或文件夹关联的 permissions 资源设置这些字段。
例如,当 Alex 登录您的应用并尝试共享文件时,系统会检查 Alex 的角色是否具有该文件的权限。如果该角色允许 Alex 共享文件,则与该文件相关的 capabilities(例如 canShare)会根据该角色进行设置。如果 Alex 想要共享该文件,您的应用会检查 capabilities,以确保 canShare 设置为 true。
获取文件功能
当您的应用打开文件时,应检查文件的功能并呈现界面,以反映当前用户的权限。例如,如果用户没有该文件的 canComment 功能,则应在界面中停用评论功能。
如需检查功能,请对 files 资源调用 get
方法,并将 fileId
路径参数和 fields 参数设置为 capabilities 字段。如需详细了解如何使用 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 参数
如果您想指定要在响应中返回的字段,可以使用
fields 系统
参数
设置 permissions 资源的任何方法。如果您省略 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,以便将
特定网域与该权限关联。
如需创建权限,请执行以下操作:
- 对
create方法使用permissions资源,并为关联的文件或文件夹提供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 all permissions 方法列出所有权限。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"
}
]
}更新权限
如需更新文件或文件夹的权限,您可以更改分配的角色。如需详细了解如何查找角色来源,请参阅确定角色来源。
对
update资源调用permissions方法,并将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"
}确定角色来源
如需更改文件或文件夹的角色,您必须知道角色的来源。 对于共享云端硬盘,角色的来源可以是共享云端硬盘的成员资格、文件夹的角色或文件的角色。
如需确定共享云端硬盘或该云端硬盘中内容的角色来源,
请对 get 资源调用
permissions 方法,并提供 fileId 和
permissionId 路径参数,并将 fields 参数设置为
permissionDetails 字段。
如需查找 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和
the 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角色才有资格获得文件夹的限时访问权限。
如需详细了解失效日期,请参阅以下文章: