跳转到主要内容
本文档详细介绍了如何对知识库中的文档、文件或文件夹进行权限变更操作。

​
功能说明

本文档介绍如何对知识库中的文档、文件或文件夹进行权限变更操作，包括：
  • 添加权限 — 为成员授予文件/文件夹的访问权限
  • 删除权限 — 移除成员对文件/文件夹的访问权限
  • 修改权限 — 变更成员对文件/文件夹的权限角色
  • 设置权限继承模式 — 控制文件/文件夹是否继承父节点的权限
  • 获取权限继承模式 — 查询当前文件/文件夹的权限继承模式
核心概念：所有权限操作都基于文件的 dentryUuid（文件唯一标识）进行，操作者需要具备对应文件的权限管理能力。

​
权限说明

以下是不同成员类型和权限角色的介绍，及不同角色所对应的能力。

​
权限角色（roleId）

进行权限变更时，需要指定权限角色：
roleId角色名称能力说明
OWNER拥有者最高权限，可读写、管理权限、分配权限
MANAGER管理者可读写、管理权限（不含分配权限）
EDITOR编辑者可查看、编辑、下载、添加
DOWNLOADER查看下载者可查看、下载
READER仅可查看者仅可查看，不可下载

​
权限成员类型（members.type）

type 值说明members.id 含义
USER用户员工 userId
ORG企业企业 ID
DEPT部门部门 ID
TAG自定义标签标签 ID
CONVERSATION会话会话 ID

​
功能实现：添加权限

调用接口 POST /v2.0/storage/spaces/dentries/{dentryUuid}/permissions，为指定成员授予对文件/文件夹的访问权限。
接口请参考添加权限文档说明，如何调用请参考如何调用服务端API文档介绍。

​
需要传入：

  • dentryUuid（Path）：目标文件/文件夹的唯一标识，通过搜索文件接口获取；
  • unionId（Query）：操作者的 unionId，可调用查询用户详情接口获取；
  • roleId（Body）：要授予的权限角色，如 EDITOR；
  • members（Body）：要授权的成员列表，每个成员需指定 type（成员类型）和 id（成员 ID）。
HTTP示例： 
POST /v2.0/storage/spaces/dentries/{dentryUuid}/permissions?unionId=操作者unionId HTTP/1.1
Host: api.dingtalk.io
x-acs-dingtalk-access-token: access_token
Content-Type: application/json

{
  "roleId": "EDITOR",
  "members": [
    {
      "type": "USER",
      "id": "员工userId",
      "corpId": "企业corpId"
    }
  ]
}

​
功能实现：修改权限

调用接口 PUT /v2.0/storage/spaces/dentries/{dentryUuid}/permissions，将指定成员的权限角色变更为新的角色。 降低权限时的重要限制：如果成员的当前权限是继承自父节点，且父节点继承来的权限角色高于目前想要设置的目标角色，则修改不会生效。
  • 示例：父目录给某用户授予了EDITOR权限，在子文件夹上将其修改为READER会失败，因为继承的 EDITOR 权限仍然生效。
  • 解决方案：需要先对该文件/文件夹调用设置权限继承模式接口，将继承模式设为BREAK（打断），切断父节点权限的传递，再进行权限修改。
接口请参考修改权限文档说明，如何调用请参考如何调用服务端API文档介绍。

​
需要传入：

  • dentryUuid（Path）：目标文件/文件夹的唯一标识，通过搜索文件接口获取；
  • unionId（Query）：操作者的 unionId，可调用查询用户详情接口获取；
  • roleId（Body）：修改后的目标权限角色（如从EDITOR改为READER）；
  • members（Body）：要修改权限的成员列表。
HTTP示例： 
PUT /v2.0/storage/spaces/dentries/{dentryUuid}/permissions?unionId=操作者unionId HTTP/1.1
Host: api.dingtalk.io
x-acs-dingtalk-access-token: access_token
Content-Type: application/json

{
  "roleId": "READER",
  "members": [
    {
      "type": "USER",
      "id": "员工userId",
      "corpId": "企业corpId"
    }
  ]
}

​
功能实现：删除权限

调用接口 POST /v2.0/storage/spaces/dentries/{dentryUuid}/permissions/remove，移除指定成员对文件/文件夹的访问权限。
接口请参考删除权限文档说明，如何调用请参考如何调用服务端API文档介绍。

​
需要传入：

  • dentryUuid（Path）：目标文件/文件夹的唯一标识，通过搜索文件接口获取；
  • unionId（Query）：操作者的 unionId，可调用查询用户详情接口获取；
  • roleId（Body）：要删除的权限角色（必须与成员当前实际持有的角色一致）；
  • members（Body）：要删除权限的成员列表。
HTTP示例： 
POST /v2.0/storage/spaces/dentries/{dentryUuid}/permissions/remove?unionId=操作者unionId HTTP/1.1
Host: api.dingtalk.io
x-acs-dingtalk-access-token: access_token
Content-Type: application/json

{
  "roleId": "EDITOR",
  "members": [
    {
      "type": "USER",
      "id": "员工userId",
      "corpId": "企业corpId"
    }
  ]
}

​
功能实现：设置权限继承模式

调用接口 PUT /v2.0/storage/spaces/dentries/{dentryUuid}/permissions/inheritances，控制文件/文件夹是否继承父节点的权限。

​
两种继承模式：

  • PASS_ON（传递）：当前节点继承所有父节点的权限，相同成员权限取最大值（默认模式）；
  • BREAK（打断）：在当前节点打断权限传递，不再继承父节点权限，适合需要单独设置独立权限的场景。

​
说明

  • BREAK模式不支持对OWNER和MANAGER角色打断。
  • 接口请参考设置权限继承模式文档说明，如何调用请参考如何调用服务端API文档介绍。

​
需要传入：

  • dentryUuid（Path）：目标文件/文件夹的唯一标识，通过搜索文件接口获取；
  • unionId（Query）：操作者的 unionId，可调用查询用户详情接口获取；
  • inheritance（Body）：继承模式PASS_ON或BREAK。
HTTP示例： 
PUT /v2.0/storage/spaces/dentries/{dentryUuid}/permissions/inheritances?unionId=操作者unionId HTTP/1.1
Host: api.dingtalk.io
x-acs-dingtalk-access-token: access_token
Content-Type: application/json

{
  "inheritance": "BREAK"
}

​
功能实现：获取权限继承模式

调用接口 GET /v2.0/storage/spaces/dentries/{dentryUuid}/permissions/inheritances，查询当前文件/文件夹的权限继承模式。

​
说明

  • 接口会返回inheritance字段，值为PASS_ON（传递）或BREAK（打断）。
  • 接口请参考获取权限继承模式文档说明，如何调用请参考如何调用服务端API文档介绍。

​
需要传入：

  • dentryUuid（Path）：目标文件/文件夹的唯一标识，通过搜索文件接口获取；
  • unionId（Query）：操作者的 unionId，可调用查询用户详情接口获取；
HTTP示例： 
GET /v2.0/storage/spaces/dentries/{dentryUuid}/permissions/inheritances?unionId=操作者unionId HTTP/1.1
Host: api.dingtalk.io
x-acs-dingtalk-access-token: access_token
Content-Type: application/json

​
典型场景及操作步骤

​
场景一：给某用户添加文件编辑权限

  1. 通过搜索文件接口，获取目标文件的 dentryUuid；
  2. 通过查询用户详情接口，获取目标用户的userId和操作者的unionId
  3. 调用添加权限接口，roleId = "EDITOR"，members[0].type = "USER"，members[0].id = 目标用户 userId。

​
场景二：将某用户的权限从编辑者降级为只读

  1. 通过搜索文件接口，获取目标文件的 dentryUuid；
  2. 通过查询用户详情接口，获取目标用户的userId；
  3. 调用修改权限接口，roleId = "READER"，members指定目标用户。

​
场景三：移除某用户对文件的所有权限

  1. 通过搜索文件接口，获取目标文件的 dentryUuid；
  2. 通过查询用户详情接口，获取目标用户的userId；
  3. 调用删除权限接口，roleId 填写该用户当前持有的权限角色，members 指定目标用户。

​
场景四：为某个子文件夹设置独立权限（不继承父目录）

  1. 通过搜索文件接口，获取子文件夹的 dentryUuid；
  2. 调用设置权限继承模式接口，inheritance = "BREAK"打断权限继承；
  3. 再调用添加权限接口，单独为该文件夹配置所需的权限成员和角色。

​
注意事项

  • 操作者（unionId）需要具备对应文件的权限管理能力，否则会返回权限不足错误。
  • 删除权限时，roleId 必须与成员当前实际持有的权限角色一致，否则操作无效。
  • OWNER和MANAGER角色的权限不支持通过 BREAK 模式打断继承。
  • members列表单次最多传 30 个成员，超出需分批调用。
  • 目前所有权限接口仅企业内部应用支持，第三方应用暂不支持。