chenmingxuan/EP-Hub-Skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
127bcc4ad3b6eb6efc8e0221258959e7ae85acb1
EP-Hub-Skill/.agents/skills/dingtalk-aitable/references/aitable/aitable-advperm.md
T
chenmingxuan 0c8fa2653e first commit
2026-09-02 11:44:52 +08:00

10 KiB
Raw Blame History

advperm — 高级权限管理

控制 Base 的高级权限总开关，并管理自定义角色（增删改查 + 子角色权限规则）。 适用场景："如何控制谁能看/改 Base 数据"、"开启/关闭高级权限"、"新建/修改/删除角色"、"按字段或行配置权限"。

命令一览

命令 用途
advperm enable 开启 Base 高级权限总开关
advperm disable 关闭 Base 高级权限总开关（高危）
advperm role-list 列出 Base 下全部角色
advperm role-get 获取单角色完整配置
advperm role-create 创建自定义角色
advperm role-update 增量更新自定义角色（PATCH 语义）
advperm role-delete 删除自定义角色（不可逆）

所有子命令的 --base-id 必填，可用隐藏别名 --base。

命令详情

advperm enable — 开启高级权限

dws aitable advperm enable --base-id BASE_ID --format json

返回 {baseId, enabled: true}。

只有开启后角色配置才会真正限制成员的可访问范围；关闭状态下角色配置仍可读但不生效。

advperm disable — 关闭高级权限（高危）

dws aitable advperm disable --base-id BASE_ID --yes --format json

返回 {baseId, enabled: false}。关闭后所有角色配置即刻失效，全员回退到默认权限。涉及多人协作或敏感数据务必和用户二次确认，建议先 role-list 留底。

advperm role-list — 列出全部角色

dws aitable advperm role-list --base-id BASE_ID --format json

返回结构：

{
  "data": {
    "enabled": true,
    "defaultRole": { "mode": 0 },
    "roles": [
      {
        "roleId": "10685308981",
        "name": "可查看角色",
        "roleType": "custom",
        "system": false,
        "subRoles": [
          {
            "authLevel": "read",
            "targetId": "HMEaRQ4",
            "targetType": "sheet",
            "config": { "actions": 268435455 },
            "display": {
              "authLevelLabel": "仅查看",
              "targetTypeLabel": "数据表",
              "permissionScopeNote": "...",
              "actionsLabels": ["新增视图", "删除视图", "修改视图"],
              "actionsNote": "..."
            }
          }
        ]
      }
    ]
  }
}

关键字段：

  • roleType：custom（自定义） / system_editor / system_reader / 5000（owner） / 4000（manager）。
  • system：boolean，true 表示系统角色（不可删）。
  • subRoles[].display.*：服务端返回的人类可读标签，可直接拼接给用户阅读，无需自行映射枚举。
  • 不返回角色成员列表；如需"成员-角色"映射请去 AI 表格 Web 端。
  • 新建 Base 默认 enabled=false，开启后只有 owner / manager 两个 meta 角色；system_editor / system_reader 需要在 Web UI 给成员授权"可编辑/可查看"后才会被服务端自动生成。

role-list / role-get 不需要管理员权限，普通成员也可读。

advperm role-get — 获取单角色配置

dws aitable advperm role-get --base-id BASE_ID --role-id ROLE_ID --format json

返回结构同 role-list 中单个 role 对象（含完整 subRoles[].config 字段/行级规则与 display.* 标签）。

advperm role-create — 创建自定义角色

# 仅指定 name，子角色由服务端按默认（none）填充
dws aitable advperm role-create --base-id BASE_ID --name "市场可读" --format json

# 创建时即指定 sub-roles（推荐——避免再走一次 role-update）
dws aitable advperm role-create --base-id BASE_ID --name "市场可读" \
  --sub-roles '[{"targetId":"<sheetId>","targetType":"sheet","authLevel":"read"}]' --format json
flag 必填 说明
--name ✅ 角色名称
--role-type 角色类型字符串（留空由服务端决定默认值，如 custom）
--flow-type 流程类型字符串（按业务需要）
--sub-roles JSON 数组：[{targetId, targetType, authLevel, appId?, config?}]，详见下方"sub-roles 子字段"段

返回新建角色的完整配置（同 role-get 出参格式，含自动生成的 default subRoles）。 系统角色无法通过本命令创建。

advperm role-update — 增量更新自定义角色（PATCH 语义）

# 只改名
dws aitable advperm role-update --base-id BASE_ID --role-id ROLE_ID --name "新名字"

# 只改 sheet 子角色 authLevel，name 不传保持不变
dws aitable advperm role-update --base-id BASE_ID --role-id ROLE_ID \
  --sub-roles '[{"targetId":"<sheetId>","targetType":"sheet","authLevel":"edit-own"}]'
flag 必填 说明
--role-id ✅ 目标自定义角色 ID（数字 long 字符串）
--name 新角色名称；不传不修改
--role-type / --flow-type 可选
--sub-roles JSON 数组，PATCH 合并语义：按 (targetId, targetType) 合并到现有 subRoles，入参中的 sub 整体替换该 sub，入参未提及的 sub 保留不变（无需先调 role-get 自行 merge）

系统角色禁止更新（包括 owner / manager / system_editor / system_reader）。

sub-roles 子字段

每个 sub-role 描述「角色对某个权限目标的访问粒度」：

字段 类型 说明
targetId string 目标资源 ID（数据表 → tableId；仪表盘 → dashboardId；应用 → appId）
targetType string sheet / dashboard / app
authLevel string manage / edit-own / edit-custom-field / edit-field-range / read / none
appId string（可选） 仅 targetType=app 时使用
config object（可选） 字段/行级细化规则；含 actions（位图）/ rows / cells。结构与 role-get 出参 subRoles[].config 对齐

advperm role-delete — 删除自定义角色（不可逆）

dws aitable advperm role-delete --base-id BASE_ID --role-id ROLE_ID --yes --format json

要求同时满足：

  1. 该 Base 已开启高级权限（role-list 返回 enabled=true）。
  2. 当前 dws 登录用户是该 Base 的管理员/Owner。
  3. --role-id 是 role-list 返回的数字 long 字符串（如 "10685308981"），且对应角色 system=false。

不可逆，删前先 role-get 留底。

能力边界

能力 状态
开/关高级权限 ✅ 需管理员
列出 / 读取角色 ✅ 普通成员也可读
创建自定义角色 ✅ 需管理员
增量修改角色（PATCH 语义，不清空未传字段） ✅ 需管理员
删除自定义角色 ✅ 需管理员
修改/删除系统角色 ❌ 服务端禁止；只能在 AI 表格 Web 端操作
角色 ↔ 成员绑定 ❌ CLI 暂不支持，需在 AI 表格 Web 端 → Base 设置 → 高级权限 → 角色管理面板手动完成

错误码速查

场景 code type message
advperm 关闭时调用写接口（如 role-delete / role-create / role-update） ADVANCED_PERMISSION_DISABLED USER_ERROR Advanced permission is disabled for base <BASE>, please enable it via setAdvancedPermission before managing roles
非管理员调用 enable / disable / role-create / role-update / role-delete 401 AUTH_ERROR the current user must be a manager (administrator) of this base to manage roles or advanced permission
删除/更新系统角色（system=true） 600 USER_ERROR Illegal argument
操作不存在的数字 roleId（get/update/delete） 600 USER_ERROR Illegal argument
传非数字 roleId（如 owner / manager） INVALID_PARAMS INPUT_ERROR roleId is required
role-create 缺 --name INVALID_PARAMS INPUT_ERROR name is required
--sub-roles JSON 不是数组 / 解析失败 （CLI 层拦截） — --sub-roles 解析失败 ... / --sub-roles 必须是 JSON 数组
--base-id 无法解析 INVALID_BASE_ID INPUT_ERROR baseId cannot be resolved to docId

600 / Illegal argument 同时覆盖"操作系统角色"和"操作不存在 roleId"两种情况。拿到 600 时先 role-list 自查目标 roleId 是否存在、是否 system=true，再据此引导用户。

典型工作流

排查"成员看不到某些字段/记录"

dws aitable advperm role-list --base-id BASE_ID --format json
# 若 enabled=false：高级权限未开，所有规则不生效，与用户确认是否需要 enable

dws aitable advperm enable --base-id BASE_ID --format json
dws aitable advperm role-list --base-id BASE_ID --format json
# 看 roles[] 里有哪些自定义角色

dws aitable advperm role-get --base-id BASE_ID --role-id ROLE_ID --format json
# 检查 subRoles[].config 中的字段/行级权限规则

新建一个"市场可读"角色

# 1. 确保高级权限已开
dws aitable advperm enable --base-id BASE_ID --format json

# 2. 拿目标 sheet 的 tableId
dws aitable table get --base-id BASE_ID --format json

# 3. 创建角色 + 指定 sheet 子角色 authLevel=read
dws aitable advperm role-create --base-id BASE_ID --name "市场可读" \
  --sub-roles '[{"targetId":"<tableId>","targetType":"sheet","authLevel":"read"}]' \
  --format json
# → 返回新角色完整配置，含 roleId，记下后续 patch / delete 使用

升级角色权限（read → edit-own），保留其他配置

# 只传 sub-roles，name 等其他字段保持不变（PATCH 语义）
dws aitable advperm role-update --base-id BASE_ID --role-id ROLE_ID \
  --sub-roles '[{"targetId":"<tableId>","targetType":"sheet","authLevel":"edit-own"}]' \
  --format json

改角色名（不影响权限规则）

dws aitable advperm role-update --base-id BASE_ID --role-id ROLE_ID --name "新名字"

清理废弃角色

dws aitable advperm role-list --base-id BASE_ID --format json
dws aitable advperm role-delete --base-id BASE_ID --role-id ROLE_ID --yes --format json

关闭高级权限（恢复全员可见）

dws aitable advperm role-list --base-id BASE_ID --format json > /tmp/roles-backup.json
dws aitable advperm disable --base-id BASE_ID --yes --format json
Reference in New Issue View Git Blame Copy Permalink