每个 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 日期时间表示权限何时过期。到期时间具有以下限制:
- 只能针对用户和群组权限进行设置。
- 时间必须是将来的时间。
- 时间不能超过未来一年之后。
如需详细了解到期日期,请参阅以下文章:
权限传播
文件夹的权限列表会向下传播,并且所有子文件和文件夹都会从父文件继承权限。每当权限或层次结构发生更改时,内容都会以递归方式传播到所有嵌套文件夹。例如,如果某个文件存在于某个文件夹中,然后该文件夹随后移动到另一个文件夹中,则对该新文件夹的权限会传播到该文件。如果新文件夹向文件的用户授予新角色(例如“writer”),则该角色会覆盖其旧角色。
相反,如果某个文件从某个文件夹继承 role=writer
,然后被移动到另一个提供“reader”角色的文件夹,则该文件现在会继承 role=reader
。
无法从共享云端硬盘的文件或文件夹中移除继承的权限。 相反,您必须在继承这些权限的直接或间接父级上调整这些权限。可以从“我的云端硬盘”或“与我共享”下的内容中移除继承的权限。
相反,对“我的云端硬盘”中文件或文件夹的继承权限也可以被覆盖。因此,如果文件从“我的云端硬盘”文件夹继承 role=writer
,您可以为该文件设置 role=reader
以降低其权限级别。
功能
权限资源最终不能决定当前用户对文件或文件夹执行操作的能力。而是 Files 资源包含一组布尔值 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"
}
]
}
验证用户权限
当应用打开文件时,应检查该文件的功能并呈现界面,以反映当前用户的权限。例如,如果用户对文件没有 canComment
功能,则应在界面中停用评论功能。
如需详细了解 capabilities
,请参阅上面的功能部分。
如需检查这些 capability,请调用 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, "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 } }
确定共享云端硬盘文件和文件夹的角色来源
要更改针对文件或文件夹的角色,您必须知道角色的来源。 对于共享云端硬盘,角色的来源可以基于共享云端硬盘的成员资格、文件夹中的角色或文件的角色。
如需确定某个共享云端硬盘的角色来源,或该云端硬盘中所含项的角色来源,请调用 permissions.get
,同时将 fileId
、permissionId
和 fields
参数设置为 permissionDetails
字段。如需查找 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
来撤消访问权限。如果成功,响应正文将为空。如需确认权限已移除,请将 permissions.list
与 fileId
搭配使用。
请求
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
。
使用批量请求更改多项权限
我们强烈建议您使用批量请求来修改多项权限。
以下是使用客户端库执行批量权限修改的示例。