每个 Google 云端硬盘文件、文件夹和共享云端硬盘都与
permissions 资源。每个资源
标识特定 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
,然后移至
另一个提供“阅读器”的文件夹则文件现在会继承
role=reader
。
您无法为共享云端硬盘的文件或文件夹移除继承的权限。 相反,必须针对直接或间接父级调整这些权限, 它们是继承而来的您可为下的内容移除继承的权限 “我的云端硬盘”或“与我共享”
反之,在“我的文件夹”中,可以覆盖文件或文件夹继承的权限
云端硬盘。因此,如果文件继承 role=writer
继承自 My
云端硬盘文件夹,您可以在该文件上设置 role=reader
,以降低其
权限级别。
功能
Permissions 资源最终不会
决定当前用户能否对文件或文件夹执行操作。
相反,Files资源包含一系列
布尔值 capabilities
字段,用于指示是否可以
对文件或文件夹执行的操作。Google Drive API 会根据
与文件或文件夹关联的当前用户的权限资源。
例如,当阿力登录您的应用并尝试共享文件时,阿力的角色
检查文件权限。如果该角色允许他们共享文件,
与文件相关的 capabilities
(例如 canShare
)已填充
角色的相对位置。如果阿力想要分享该文件,您的应用会检查
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"
}
]
}
验证用户权限
当您的应用打开文件时,它应检查文件的 capability 并呈现
以反映当前用户的权限。例如,如果用户
不具备对文件的 canComment
功能,
应在界面中停用
如需详细了解 capabilities
,请参阅 Capabilities
部分。
如需检查功能,请使用以下代码调用 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
,请使用
使用 fileId
的 permissions.list
。接收者
提取 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
}
]
}
更改权限
如需更改文件或文件夹的权限,您可以更改已分配的角色:
使用以下代码调用
permissions.update
: 需要更改的权限的permissionId
以及用于更改权限的fileId
关联的文件、文件夹或共享云端硬盘。如需查找permissionId
,请使用 使用fileId
的permissions.list
。在请求中,找到新的
role
。
您可以授予共享云端硬盘中个别文件或文件夹的权限,甚至可以
如果用户或群组已经是成员,则会发生该错误。例如,Alex 有 role=commenter
包含在共享云端硬盘成员资格中。但是,您的应用可以让小伟
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"
}
撤消对文件或文件夹的访问权限
要撤消对文件或文件夹的访问权限,请调用
将 delete
替换为 fileId
和
permissionId
删除权限。
对于“我的云端硬盘”中的内容,则可以删除继承的 权限。删除继承的权限会撤消对该项的访问权限,并且 子项(如果有)。
对于共享云端硬盘中的内容,继承的权限无法撤消。更新或 改为撤消对父级文件或文件夹的权限。
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
)。
将文件所有权从一个消费者账号转移到另一个消费者账号
文件所有权可以在个人用户账号之间转移。 不过,云端硬盘不会在 Google 云端硬盘之间转移文件所有权 消费者 账号 直到潜在的新所有者明确同意转移。转移 将文件所有权从一个消费者账号转移到另一个消费者账号:
当前所有者通过创建或更新请求来启动所有权转让 潜在新所有者的文件权限。该权限必须包含 这些设置:
role=writer
、type=user
和pendingOwner=true
。如果 新所有者正在为潜在所有者创建权限,电子邮件地址 系统会向新的潜在所有者发送通知,告知对方 文件的所有权。新所有者接受所有权转让请求,方法是创建或更新 文件的权限。该权限必须包含以下设置:
role=owner
和transferOwnership=true
。如果新所有者创建了 新权限,则系统会向先前的所有者发送电子邮件通知 表明所有权已转让。
文件转移后,之前所有者的角色会降级为“writer
”。
通过批量请求更改多项权限
我们强烈建议您使用 批量请求用于修改多个 权限。
以下示例展示了如何使用 客户端库。