访问提案是指请求者向审批者提交的提案,旨在授予收件人对 Google 云端硬盘内容的访问权限。
审批者可以查看并处理云端硬盘文件中所有未解决的访问权限提案。这意味着,您可以通过以程序化方式查询访问提案,然后解决这些提案,来加快审批流程。此外,审批者还可以查看汇总的提案。
Google Drive API 提供了 accessproposals 资源,以便您查看和解决待处理的访问权限提案。accessproposals资源的方法适用于文件、文件夹、共享云端硬盘中的文件,但不适用于共享云端硬盘。
以下术语专门用于访问权限提案:
- 请求者:针对云端硬盘内容发起访问提案的用户。
- 接收者:如果访问权限提案获得批准,则接收者是获得文件额外权限的用户。很多时候,收件人与请求者相同,但并非总是如此。
- 审批人:负责审批(或拒绝)访问权限提案的用户。这通常是因为他们是文档的所有者,或者他们有权共享文档。
使用 fields 参数
如果您想指定要在响应中返回的字段,可以使用 accessproposals 资源的任何方法设置 fields system 参数。如果您省略 fields 参数,服务器会返回一组特定于相应方法的默认字段。如需返回其他字段,请参阅返回特定字段。
获取待处理的访问权限提案
如需获取访问提案,请对 accessproposals 资源使用 get 方法,并提供 fileId 和 proposalId 路径参数。如果您不知道提案 ID,可以使用 list 方法列出待处理的访问权限提案。
列出待处理的访问权限提案
如需列出云端硬盘项目中的所有待处理访问权限提案,请对 accessproposals 资源调用 list 方法,并添加 fileId 路径形参。
只有文件的审批者才能列出文件中的待处理提案。审批者是指对文件具有 can_approve_access_proposals 功能的用户。如果请求者不是审批者,则返回空列表。如需详细了解 capabilities,请参阅了解文件功能。
响应正文包含一个 accessproposals 对象,表示文件上未解决的访问提案的列表。
accessproposals 对象包含有关每项提案的信息,例如请求者、接收者以及请求者添加的消息。它还包含一个 RoleAndView 对象,该对象将请求者的提议 role 与 view 分组。由于 role 是重复字段,因此每个提案可以有多个值。例如,提案可能包含一个具有 role=reader 和 view=published 的 RoleAndView 对象,以及一个仅具有 role=writer 值的额外 RoleAndView 对象。如需了解详情,请参阅视图。
传递以下查询参数可自定义访问建议的分页或过滤访问建议:
pageToken:从之前的列表调用接收的页面令牌。提供此令牌可检索后续页面。pageSize:每页返回的访问权限提案数上限。
解决待处理的访问权限提案
如需解决 Drive 项目中的所有待处理访问权限提案,请对 accessproposals 资源调用 resolve 方法,并添加 fileId 和 proposalId 路径参数。
resolve 方法包含一个 action 查询参数,用于表示对提案采取的操作。Action 对象会跟踪提案的状态变化,以便我们了解提案是被接受还是被拒绝。
resolve 方法还包含可选的查询参数 role 和 view。仅支持 writer、commenter 和 reader 角色。如果未指定角色,则默认为 reader。如需了解详情,请参阅角色和权限。sendNotification 的一个额外的可选查询参数,可让您在提案被接受或拒绝时向请求者发送电子邮件通知。
与 list 方法一样,解决提案的用户必须对文件具有 can_approve_access_proposals 功能。如需详细了解 capabilities,请参阅了解文件功能。
提案的解决方式与共享云端硬盘资源的场景下列出的模式相同。如果同一用户有多个提案,但角色不同,则适用以下规则:
- 如果一个提案被接受,另一个被拒绝,则接受的提案中的角色将应用于相应云端硬盘项目。
- 如果两个提案同时被接受,则应用权限较高的提案(例如,
role=writer与role=reader相比,role=writer的权限更高)。相应内容中会移除其他访问权限提案。
向 resolve 方法发送提案后,共享操作即完成。不再通过 list 方法返回已解决的访问提案。提案获得批准后,用户必须使用 permissions 资源来更新文件或文件夹的权限。如需了解详情,请参阅更新权限。