飞书开放平台 Server API 文档

主题

更新自定义角色 ​

更新多维表格高级权限中自定义的角色。

Warning: 更新自定义角色为增量更新，仅对传值的字段进行更新，不传值则不更新。推荐使用新版更新自定义角色接口，支持高级权限 2.0 版本新增的权限点位，包括更精细的行级别权限控制、多维表格的复制、导出点位的控制等。

前提条件 ​

要调用自定义角色相关接口，你需确保多维表格已开启高级权限。你可通过更新多维表格元数据接口开启高级权限。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/bitable/v1/apps/:app_token/roles/:role_id
HTTP MethodPUT
接口频率限制10 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可base:role:update 更新自定义角色 bitable:app 查看、评论、编辑和管理多维表格

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
app_tokenstring多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： app_token.png
- 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。
了解更多，参考多维表格 app_token 获取方式。
示例值："appbcbWCzen6D8dezhoCH2RpMAh"
role_idstring多维表格高级权限中自定义角色的唯一标识，以 rol 开头。获取方式：通过列出自定义角色接口获取。
示例值："roljRpwIUt"

请求体 ​

名称类型必填描述
role_namestring是自定义角色名称
示例值："自定义角色1"
table_rolesapp.role.table_role\[\]是针对数据表的权限设置
数据校验规则：
- 最大长度：100
  └ table_permint是数据表权限。
提示：协作者可编辑自己的记录 和 可编辑指定字段 是 可编辑记录 的特殊情况，可通过指定 rec_rule 或 field_perm 参数实现相同的效果。
示例值：0
可选值有：
- 0: 无权限 - 1: 可阅读 - 2: 可编辑记录 - 4: 可编辑字段和记录
默认值：0
  └ table_namestring否数据表名称
示例值："数据表1"
  └ table_idstring否多维表格数据表的唯一标识。获取方式： - 你可通过多维表格 URL 获取 table_id，下图高亮部分即为当前数据表的 table_id - 也可通过列出数据表接口获取 table_id

示例值："tblKz5D60T4JlfcT"
  └ rec_ruleapp.role.table_role.rec_rule否记录筛选条件，当 table_perm 为 1 或 2 时生效。用于指定可编辑或可阅读的记录。
    └ conditionsapp.role.table_role.rec_rule.condition\[\]是记录筛选条件，用于指定可编辑或可阅读的记录。
数据校验规则：
- 最大长度：100
      └ field_namestring是条件字段的名称。记录筛选条件是“创建人包含访问者本人”时，此参数值为 ""。
示例值："单选"
      └ operatorstring否条件运算符
示例值："is"
可选值有：
- is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
默认值：is
      └ valuestring\[\]否条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。
示例值：["optbdVHf4q"]
    └ conjunctionstring否多个筛选条件的关系
示例值："and"
可选值有：
- and: 与 - or: 或
默认值：and
    └ other_permint否其他记录权限，仅当 table_perm 为 2 时生效。
示例值：0
可选值有：
- 0: 禁止查看 - 1: 仅可阅读
默认值：0
  └ field_permmap<string, int>否字段权限，仅在 table_perm 为 2 时生效。用于设置字段可编辑或可阅读。类型为 map，key 是字段名称，value 是字段权限。value 枚举值有： - 1：可阅读 - 2：可编辑
示例值：{"姓名": 1, "年龄": 2}
  └ allow_add_recordboolean否新增记录权限，仅当 table_perm 为 2 时生效。用于设置记录是否可以新增。
示例值：true
默认值：true
  └ allow_delete_recordboolean否删除记录权限，仅当 table_perm 为 2 时生效。用于设置记录是否可以删除。
示例值：true
默认值：true
block_rolesapp.role.block_role\[\]否针对仪表盘的权限设置
数据校验规则：
- 最大长度：100
  └ block_idstring是多维表格仪表盘的唯一标识，以 blk 开头。获取方式：
- 在多维表格的 URL 地址栏中，block_id 是下图中高亮部分： image.png - 通过列出仪表盘接口获取
示例值："blknkqrP3RqUkcAW"
  └ block_permint是仪表盘的权限
示例值：0
可选值有：
- 0: 无权限 - 1: 可阅读
默认值：0

请求体示例 ​

json
{
    "role_name": "自定义角色1",
    "table_roles": [
        {
            "table_perm": 0,
            "table_name": "数据表1",
            "table_id": "tblKz5D60T4JlfcT",
            "rec_rule": {
                "conditions": [
                    {
                        "field_name": "单选",
                        "operator": "is",
                        "value": [
                            "optbdVHf4q"
                        ]
                    }
                ],
                "conjunction": "and",
                "other_perm": 0
            },
            "field_perm": {
                "姓名": 1,
                "年龄": 2
            },
            "allow_add_record": true,
            "allow_delete_record": true
        }
    ],
    "block_roles": [
        {
            "block_id": "blknkqrP3RqUkcAW",
            "block_perm": 0
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ roleapp.role自定义角色列表
    └ role_namestring自定义角色名称
    └ role_idstring自定义角色 ID
    └ table_rolesapp.role.table_role\[\]针对数据表的权限设置
      └ table_permint数据表权限。
提示：协作者可编辑自己的记录 和 可编辑指定字段 是 可编辑记录 的特殊情况，可通过指定 rec_rule 或 field_perm 参数实现相同的效果。
可选值有：
- 0: 无权限 - 1: 可阅读 - 2: 可编辑记录 - 4: 可编辑字段和记录
      └ table_namestring数据表名称
      └ table_idstring数据表 ID。详情参考数据表 table。
      └ rec_ruleapp.role.table_role.rec_rule可编辑或可阅读的记录。当 table_perm 为 1 或 2 时生效。
        └ conditionsapp.role.table_role.rec_rule.condition\[\]记录筛选条件，用于指定可编辑或可阅读的记录。
          └ field_namestring条件字段的名称。记录筛选条件是“创建人包含访问者本人”时，此参数值为 ""。
          └ operatorstring条件运算符
可选值有：
- is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
          └ valuestring\[\]条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。
          └ field_typeint字段类型。枚举参考字段类型 type。
        └ conjunctionstring多个筛选条件的关系
可选值有：
- and: 与 - or: 或
        └ other_permint其他记录权限，仅在 table_perm 为 2 时生效。
可选值有：
- 0: 禁止查看 - 1: 仅可阅读
      └ field_permmap<string, int>字段权限，仅在 table_perm 为 2 时生效。用于设置字段可编辑或可阅读。类型为 map，key 是字段名称，value 是字段权限。value 枚举值有： - 1：可阅读 - 2：可编辑
      └ allow_add_recordboolean新增记录权限，仅在 table_perm 为 2 时生效，用于设置记录是否可以新增。
      └ allow_delete_recordboolean删除记录权限，仅在 table_perm 为 2 时生效，用于设置记录是否可以删除。
    └ block_rolesapp.role.block_role\[\]针对仪表盘的权限设置
      └ block_idstring仪表盘的 ID。详情参考仪表盘 block。
      └ block_typestring仪表盘的类型
可选值有：
- dashboard: 仪表盘
      └ block_permint仪表盘的权限
可选值有：
- 0: 无权限 - 1: 可阅读

响应体示例 ​

json
{
    "data": {
        "role": {
            "role_name": "role1",
            "table_roles": [
                {
                    "table_name": "table1",
                    "table_id": "tblFIgBzKEq75HSE",
                    "table_perm": 2,
                    "addrecords_perm": false,
                    "deleterecords_perm": true,
                    "rec_rule": {
                        "conjunction": "or",
                        "conditions": [
                            {
                                "field_name": "单选",
                                "operator": "is",
                                "field_type": 3,
                                "value": [
                                    "optbdVHf4q"
                                ]
                            },
                            {
                                "value": null,
                                "field_name": "人员",
                                "operator": "contains",
                                "field_type": 11
                            },
                            {
                                "operator": "contains",
                                "field_type": 1003,
                                "value": null,
                                "field_name": ""
                            }
                        ],
                        "other_perm": 0
                    },
                    "field_perm": {
                        "单选": 1,
                        "年龄": 2
                    }
                },
                {
                    "table_name": "table2",
                    "table_id": "tblMPI6OC1aWvTvs",
                    "table_perm": 1,
                    "rec_rule": {
                        "conditions": [
                            {
                                "field_name": "人员",
                                "operator": "contains",
                                "field_type": 11,
                                "value": null
                            },
                            {
                                "operator": "is",
                                "field_type": 4,
                                "value": [
                                    "opttgKOTSt",
                                    "optWcdXR0W"
                                ],
                                "field_name": "多选"
                            }
                        ],
                        "other_perm": 0,
                        "conjunction": "and"
                    }
                },
                {
                    "table_name": "table3",
                    "table_id": "tblmkLF7Tg6IWbRb",
                    "table_perm": 0
                },
                {
                    "table_name": "table4",
                    "table_id": "tbl5VQHDTms19Qe7",
                    "table_perm": 4
                }
            ],
            "block_roles": [
                {
                    "block_id": "blknkqrP3RqUkcAW",
                    "block_perm": 0
                },
                {
                    "block_id": "blkAjxjWKvbBi7EA", 
                    "block_perm": 1
                }
            ]
        }
    },
    "code": 0,
    "msg": "success"
}

错误码 ​

HTTP状态码错误码描述排查建议
2001254000WrongRequestJson请求体错误
2001254001WrongRequestBody请求体错误
2001254002Fail导致报 1254002 错误码的场景较多，请参考以下建议排查： - 如果单次操作的内容变更较大，请尝试在单次操作中减少数据量 - 如果你并发调用了接口，请尝试控制请求间隔，稍后重试 - 如果在知识库（wiki）中创建多维表格，请检查你是否使用了知识库创建知识空间节点接口创建多维表格。在此场景下不能使用创建多维表格接口 - 请检查接口参数是否有误。例如，在分页查询多维表格时，传递了无效的 page_token，或传递了错误的数据表的 table_id - 如果该报错偶尔发生，可能是服务器超时或不稳定，请重试解决
2001254003WrongBaseTokenapp_token 错误。app_token 是多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： app_token.png - 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。 了解更多，参考多维表格 app_token 获取方式。
2001254010ReqConvError请求错误
4001254032InvalidRoleName自定义角色名无效
4001254033RoleNameDuplicated自定义角色名重复
4001254036Base is copying, please try again later.复制多维表格为异步操作，该错误码表示当前多维表格仍在复制中，在复制期间无法操作当前多维表格。需要等待复制完成后再操作
2001254040BaseTokenNotFoundapp_token 不存在。app_token 是多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： app_token.png - 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。 了解更多，参考多维表格 app_token 获取方式。
4041254047RoleIdNotFoundrole_id 不存在。role_id 是多维表格高级权限中自定义角色的唯一标识，以 rol 开头。可通过列出自定义角色接口获取。
4001254110RoleExceedLimit自定义角色数量超限，限制 30 条
2001254290TooManyRequest请求过快，稍后重试
2001254291Write conflict在同一个数据表中，并发调用了读写接口或请求过快，出现冲突。请参考以下建议解决： - 确保没有并发调用多维表格读写相关接口 - 若操作量较大，建议在接口与接口之间增加 0.5 或 1 秒的延迟，也可在报错中增加重试逻辑，确保业务的稳定性 - 对于写接口，可以将接口中的查询参数 ignore_consistency_check 设置为 true，表示在读写操作时，暂时忽略一致性检查，以提高性能
4001254301OperationTypeError多维表格未开启高级权限或不支持开启高级权限
4031254302Permission denied.调用身份缺少多维表格的高级权限。你需给予调用身份数据表的 可管理 权限或多维表格的 可管理 等权限，再重新调用。具体步骤如下所示： - 对用户授予高级权限，你可在 多维表格高级权限设置 中添加用户，为用户开通足够权限；或在多维表格页面右上方 分享 入口为当前用户添加可管理权限。详情参考飞书帮助中心文档使用多维表格高级权限。 - 对应用授予高级权限，你需通过多维表格页面右上方 「...」 -> 「...更多」 ->「添加文档应用」 入口为应用添加可管理权限。 image.png 注意： 在 添加文档应用 前，你需确保目标应用至少开通了一个多维表格的 API 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 你也可以在 多维表格高级权限设置 中添加用户或一个包含应用的群组，给予这个群自定义的读写等权限。
4031254304Only Available For Business and Enterprise Editions仅企业版和旗舰版飞书支持行列权限
2001255001InternalError内部错误，请联系技术支持
2001255002RpcError内部错误，请联系技术支持
2001255003MarshalError序列化错误，请联系技术支持
2001255004UmMarshalError反序列化错误，请联系技术支持
5041255040Request timed out, please try again later请求超时，进行重试

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有