权限概述
权限是指在云文档相关资源中，应用或用户对各类云文档资源，如文件夹、文档、电子表格、多维表格、知识库等的可阅读、可编辑、可管理等权限。本文档介绍云文档权限相关的基本概念、接入流程、方法列表等。
基本概念
以下为云文档权限相关的基础概念。了解更多，参考飞书帮助中心文档云文档权限概念介绍。
| 概念 | 描述 |
|---|---|
| 云文档 | 飞书提供文档、表格、多维表格等多种内容类型，你也可以将本地文件上传至飞书云文档。以上内容统称为云文档。 |
| 所有者 | 云文档、文件、文件夹的所有者。 |
| 协作者 | 有可阅读、可编辑或可管理权限的云文档、文件、文件夹的成员。 |
| 协作者权限 | 云文档和文件夹支持 3 种权限类型：阅读、编辑、管理。 |
| 可阅读 | - 有可阅读权限的协作者只能阅读文档和文件夹内的文档内容。 - 可移除同为可阅读权限的协作者。 |
| 可编辑 | - 有可编辑权限的协作者可以阅读、编辑文档和文件夹内的文档内容。 - 可修改、移除有阅读、可编辑权限的协作者。 |
| 可管理 | - 有可管理权限的协作者可以阅读、编辑文档和文件夹内的文档内容。 - 可修改、移除有阅读、编辑、可管理权限的协作者。 - 可管理文档权限设置。 - 文档所有者的权限类型也是可管理权限，且可转移文档所有权。 |
接入流程
| 序号 | 步骤 | 操作方法 |
|---|---|---|
| 1 | 创建应用 | 根据应用的使用场景选择创建企业自建应用 或创建应用商店应用 |
| 2 | 申请接口调用权限 | 根据需要调用的接口文档中描述的「权限要求」到开发者后台申请应用权限 |
| 3 | 访问应用自有资源 | 访问凭证使用 tenant_access_token 可以直接访问应用自有资源： 文件夹、文档、电子表格、多维表格 |
| 4 | 访问用户自有资源 | 访问凭证使用 user_access_token 可以直接访问用户自有资源： 文件夹、文档、电子表格、多维表格 |
| 5 | 使用tenant_access_token访问应用非自有资源 | 1. 访问其他用户的文档、电子表格、多维表格 需要取得文档所有者的授权 - 需要应用开启机器人能力 - 需要所有者打开对应的文档，在页面右上方「...」->「...更多」-> 「添加文档应用」入口添加 2. 访问 知识库需要获得知识库管理员的授权 - 需要应用开启机器人能力 - 需要知识库管理员打开知识库节点文档，在页面右上方「...」->「...更多」-> 「添加文档应用」入口添加 |
| 6 | 使用user_access_token访问用户非自有资源 | 1. 访问其他用户的文档、电子表格、多维表格 需要取得文档所有者的授权 - 需要所有者打开对应的文档，在页面右上方「分享」入口添加 2. 访问其他用户文件夹需要取得文件夹所有者的授权 - 需要所有者在我的空间找到目标文件夹，右键菜单中「分享」入口添加 3. 访问知识库需要获得知识库管理员的授权 - 需要知识库管理员打开知识库节点文档，在页面右上方「分享」入口添加 |
| 7 | 接口测试 | 你可以在 API 调试台 中快速调试这些 API ，使用方法参见API 调试台使用指南 |
| 8 | 事件订阅 | 需要到开发者后台配置事件回调地址,确保回调地址公网可访问。可参考事件监听示例、事件订阅概述 |
| 9 | 日志检索 | 当调用接口返回失败时，从返回的header部分获取 X-Tt-Logid: 20220501181xxx8035096193288FA。 再到应用管理后台，用服务端日志检索 分析问题。 |
资源介绍
云文档的权限由 成员 和 设置 两部分资源组成。参考本小节了解权限相关接口的资源说明。
成员
权限成员分为 文档所有者 和 文档协作者。
| 成员 | 描述 | 支持成员及 ID 类型 |
|---|---|---|
| 文档所有者 | 云文档、文件、文件夹的所有者。 | - 用户，支持用户邮箱、用户的 OpenID、UnionID 或 UserID。获取方式参考如何获取不同的用户 ID - 应用，支持应用的 OpenID。获取方式参考如何获取应用 open_id |
| 文档协作者 | 有可阅读、可编辑或可管理权限的云文档、文件、文件夹的成员。 | - 用户，支持用户邮箱、用户的 OpenID、UnionID 或 UserID。获取方式参考如何获取不同的用户 ID - 应用，支持应用的 OpenID。获取方式参考如何获取应用 open_id - 群组，支持 chat_id，获取方式参考群 ID 说明 - 部门，支持 open_department_id，获取方式参考部门资源介绍 - 自定义用户组，支持 group_id ，获取方式参考用户组资源介绍 - 知识库成员，支持 wikispaceid，获取方式参考知识库概述 |
设置
权限设置具体的权限点如下所示：
| 权限点 | 描述 |
|---|---|
| 允许内容被分享到组织外 | 支持允许内容仅被分享给关联组织。解关联组织，参考飞书帮助中心文档关联组织介绍。 |
| 可以复制内容 | 设置谁可以复制内容，支持设置仅可阅读、仅可编辑、仅可管理的人可复制内容。 |
| 可以创建副本、打印、下载 | 设置谁可以创建副本、打印、下载，支持设置仅可阅读、仅可编辑、仅可管理的人可创建副本、打印、下载。 |
| 可以评论 | 设置谁可以评论，支持设置仅可阅读、仅可编辑的人可评论。 |
| 谁可以查看、添加、移除协作者 | 支持两个维度设置： - 从企业组织维度，设置谁可以查看、添加、移除协作者 - 从协作者维度，设置设置谁可以查看、添加、移除协作者 |
| 链接分享设置 | 支持设置仅关联组织的可通过链接编辑或阅读。 |
| 密码 | 链接分享 设置为“互联网获得链接的人可编辑/可阅读”后，支持启用密码。 |
方法列表
成员
| 方法 (API) | 权限要求（满足任一） | 访问凭证（选择其一） | 商店 | 自建 |
|---|---|---|---|---|
[增加协作者权限](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-member/create) POST/open-apis/drive/v1/permissions/:token/members | docs:doc 查看、评论、编辑和管理文档 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:file 上传、下载文件到云空间 sheets:spreadsheet 查看、评论、编辑和管理电子表格 wiki:wiki 查看、编辑和管理知识库 | tenant_access_token user_access_token | ✓ | ✓ |
[更新协作者权限](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-member/update) PUT/open-apis/drive/v1/permissions/:token/members/:member_id | docs:doc 查看、评论、编辑和管理文档 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:file 上传、下载文件到云空间 sheets:spreadsheet 查看、评论、编辑和管理电子表格 wiki:wiki 查看、编辑和管理知识库 | tenant_access_token user_access_token | ✓ | ✓ |
[移除协作者权限](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-member/delete) DELETE/open-apis/drive/v1/permissions/:token/members/:member_id | docs:doc 查看、评论、编辑和管理文档 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:file 上传、下载文件到云空间 sheets:spreadsheet 查看、评论、编辑和管理电子表格 wiki:wiki 查看、编辑和管理知识库 | tenant_access_token user_access_token | ✓ | ✓ |
[判断协作者是否有某权限](https://open.larkoffice.com/document/ukTMukTMukTM/uYzN3UjL2czN14iN3cTN) POST/open-apis/drive/permission/member/permitted | drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:drive:readonly 查看、评论和下载云空间中所有文件 drive:file 上传、下载文件到云空间 drive:file:readonly 查看和下载云空间中的文件 docs:doc 查看、评论、编辑和管理文档 docs:doc:readonly 查看、评论和导出文档 sheets:spreadsheet 查看、评论、编辑和管理表格 sheets:spreadsheet:readonly 查看、评论和导出表格 | tenant_access_token user_access_token | ✓ | ✓ |
[获取协作者列表](https://open.larkoffice.com/document/ukTMukTMukTM/uATN3UjLwUzN14CM1cTN) POST/open-apis/drive/permission/member/list | drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:drive:readonly 查看、评论和下载云空间中所有文件 drive:file 上传、下载文件到云空间 drive:file:readonly 查看和下载云空间中的文件 docs:doc 查看、评论、编辑和管理文档 docs:doc:readonly 查看、评论和导出文档 sheets:spreadsheet 查看、评论、编辑和管理表格 sheets:spreadsheet:readonly 查看、评论和导出表格 | tenant_access_token user_access_token | ✓ | ✓ |
[转移拥有者](https://open.larkoffice.com/document/ukTMukTMukTM/uQzNzUjL0czM14CN3MTN) POST/open-apis/drive/permission/member/transfer | drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:file 上传、下载文件到云空间 docs:doc 查看、评论、编辑和管理文档 sheets:spreadsheet 查看、评论、编辑和管理表格 | tenant_access_token user_access_token | ✓ | ✓ |
权限设置
| 方法 (API) | 权限要求（满足任一） | 访问凭证（选择其一） | 商店 | 自建 |
|---|---|---|---|---|
[获取云文档权限设置](https://open.larkoffice.com/document/ukTMukTMukTM/uIzNzUjLyczM14iM3MTN/drive-v2/permission-public/get) GET/open-apis/drive/v2/permissions/:token/public | docs:doc 查看、评论、编辑和管理文档 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:drive:readonly 查看、评论和下载云空间中所有文件 drive:file 上传、下载文件到云空间 sheets:spreadsheet 查看、评论、编辑和管理电子表格 wiki:wiki 查看、编辑和管理知识库 | tenant_access_token user_access_token | ✓ | ✓ |
[更新云文档权限设置](https://open.larkoffice.com/document/ukTMukTMukTM/uIzNzUjLyczM14iM3MTN/drive-v2/permission-public/patch) PATCH/open-apis/drive/v2/permissions/:token/public | docs:doc 查看、评论、编辑和管理文档 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:file 上传、下载文件到云空间 sheets:spreadsheet 查看、评论、编辑和管理电子表格 wiki:wiki 查看、编辑和管理知识库 | tenant_access_token user_access_token | ✓ | ✓ |
[启用云文档密码](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-public-password/create) POST/open-apis/drive/v2/permissions/:token/public/password | docs:doc 查看、评论、编辑和管理文档 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:file 上传、下载文件到云空间 sheets:spreadsheet 查看、评论、编辑和管理电子表格 wiki:wiki 查看、编辑和管理知识库 | tenant_access_token user_access_token | ✓ | ✓ |
[刷新云文档密码](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-public-password/update) PUT/open-apis/drive/v2/permissions/:token/public/password | docs:doc 查看、评论、编辑和管理文档 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:file 上传、下载文件到云空间 sheets:spreadsheet 查看、评论、编辑和管理电子表格 wiki:wiki 查看、编辑和管理知识库 | tenant_access_token user_access_token | ✓ | ✓ |
[停用云文档密码](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/permission-public-password/delete) DELETE/open-apis/drive/v2/permissions/:token/public/password | docs:doc 查看、评论、编辑和管理文档 drive:drive 查看、评论、编辑和管理云空间中所有文件 drive:file 上传、下载文件到云空间 sheets:spreadsheet 查看、评论、编辑和管理电子表格 wiki:wiki 查看、编辑和管理知识库 | tenant_access_token user_access_token | ✓ | ✓ |