飞书开放平台 Server API 文档

主题

更新自定义角色(新版) ​

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

Tip: 相较于旧版接口，新版自定义角色接口支持高级权限 2.0 版本新增的权限点位，包括更精细的行级别权限控制、多维表格的复制、导出点位的控制等。

Warning: 更新自定义角色为增量更新，仅对传值的字段进行更新，不传值则不更新。

前提条件 ​

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

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/base/v2/apps/:app_token/roles/:role_id
HTTP MethodPUT
接口频率限制10 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用base:role:update 更新自定义角色

请求头 ​

名称类型必填描述
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"
数据校验规则：
- 长度范围：0 ～ 100 字符
role_idstring多维表格高级权限中自定义角色的唯一标识，以 rol 开头。获取方式：通过列出自定义角色接口获取。
示例值："roljRpwIUt"
数据校验规则：
- 长度范围：0 ～ 100 字符

请求体 ​

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

示例值："tblKz5D60T4JlfcT"
数据校验规则：
- 长度范围：0 ～ 50 字符
  └ rec_rulerec_rule否记录筛选条件，当 table_perm 为 1 或 2 时生效。用于指定可编辑或可阅读的记录。 - rec_rule字段未设置、且 table_perm 不变的情况下，保持旧值。 - 字段 value 为 {} 的情况下，表示设置为默认值，即全部可编辑或可阅读，具体权限需结合 table_perm 参数。
    └ conditionsrec_rule_condition\[\]否记录筛选条件，用于指定可编辑或可阅读的记录。
数据校验规则：
- 长度范围：0 ～ 10
      └ field_namestring是条件字段的名称。记录筛选条件是“创建人包含访问者本人”时，此参数值为 ""。
示例值："单选"
      └ operatorstring否条件运算符
示例值："is"
可选值有：
- is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
默认值：is
      └ valuestring\[\]否条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。
示例值：["optbdVHf4q"]
数据校验规则：
- 长度范围：0 ～ 50
    └ conjunctionstring否多个筛选条件的关系
示例值："and"
可选值有：
- and: 与 - or: 或
默认值：and
    └ other_permint否其他记录权限，仅在 table_perm 为 2 （数据表权限为可编辑）时生效。 - 当 other_perm 为 1 时，表示未命中 rec_rule 的记录仅可阅读，不可编辑 - 当 other_perm 为 0 时，表示既未命中 rec_rule、也未命中 other_rec_rule 的记录会被禁止阅读。即你可以通过 other_rec_rule 进一步指定可阅读的记录范围。
示例值：1
可选值有：
- 0: 禁止查看 - 1: 仅可阅读
默认值：0
  └ other_rec_ruleother_rec_rule否记录筛选条件，在 table_perm 为 2 且rec_rule.other_perm 为 0 时生效。 - 对于未命中 rec_rule 的记录，通过 other_rec_rule 指定可阅读记录范围；此时，既未命中 rec_rule、也未命中 other_rec_rule 的记录会被禁止阅读。 - other_rec_rule 字段未设置、且 table_perm 与 rec_rule 不变的情况下，将会保持旧值不变。 - other_rec_rule 字段设置为 {} 时，且 table_perm 与rec_rule 不变的情况下，表示设置为默认值，即非rec_rule 记录全部可阅读。
注意：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用获取多维表格元数据 查看。
    └ conditionsrec_rule_condition\[\]否记录筛选条件，用于指定可阅读的记录。
数据校验规则：
- 长度范围：0 ～ 10
      └ field_namestring是条件字段的名称。记录筛选条件是“创建人包含访问者本人”时，此参数值为 ""。
示例值："单选"
      └ operatorstring否条件运算符
示例值："is"
可选值有：
- is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
默认值：is
      └ valuestring\[\]否条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。
示例值：["optbdVHf4q"]
数据校验规则：
- 长度范围：0 ～ 50
    └ conjunctionstring否多个筛选条件的关系
示例值："and"
可选值有：
- and: 与 - or: 或
默认值：and
  └ field_permmap<string, int>否字段权限，仅在 table_perm 为 1和 2 时生效。用于设置字段可编辑或可阅读。类型为 map，key 是字段名称，value 是字段权限。对于未设置的多维表格字段，则为无权限。更新时，field_perm 未传值时，将保留旧值不变。field_perm 传{}时，则将所有字段设置为默认值可编辑或者可阅读，默认值需结合table_perm 字段。value 枚举值有： - 1：可阅读 - 2：可添加 - 3：可编辑
示例值：{"姓名": 1, "年龄": 2}
  └ allow_add_recordboolean否新增记录权限，仅在 table_perm 为 2 时生效，用于设置记录是否可以新增。
示例值：true
默认值：true
  └ allow_delete_recordboolean否删除记录权限，仅在 table_perm 为 2 时生效，用于设置记录是否可以删除。
示例值：true
默认值：true
  └ view_permint否设置视图的编辑权限。
示例值：2
可选值有：
- 1: 可阅读 - 2: 可编辑
默认值：2
数据校验规则：
- 取值范围：0 ～ 2
  └ view_rulesmap<string, int>否可读的视图集合，仅在 view_perm 为 1 （视图为可阅读）时生效。更新时，未设置该字段view_rules ，且 view_perm 未变化的情况下，将保留旧值。设置该字段view_rules 为{}，且 view_perm 为1的情况下，会将所有视图置为可读。
该参数类型为 map，其中 key 是视图 ID，value 是视图对应的权限。value 枚举值有： - 0：无权限 - 1：可阅读
注意：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用获取多维表格元数据 查看。
示例值：{"vewEYknYcC": 0}
  └ field_action_rulesmap<string, map<string, int>>否更新字段的权限，仅可配置单多选字段、附件字段。可选的点位有：
- select_option_edit : 选项配置点位，配置是否可增删改单、多选选项，未设置表示无权限。
- attachment_export: 附件操作权限点位，配置是否可导出附件，未设置表示可导出。
该参数类型为两层 map 结构，其中 key 是字段点位权限，value 是字段权限集合。字段权限集合也是一个 map 结构，其中 key 是字段名称，value 是字段点位权限： - 0：无权限 - 1：有权限
注意：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用获取多维表格元数据 查看。
示例值：{"select_option_edit": {"单选1":0}}
block_rolesblock_role\[\]否针对仪表盘的权限设置。更新是，未设置该字段的情况下，保持旧值不变。设置block_roles为{}时，将所有仪表盘更新为默认权限，即所有仪表盘无权限。
数据校验规则：
- 长度范围：0 ～ 100
  └ block_idstring是多维表格仪表盘的唯一标识，以 blk 开头。获取方式：
- 在多维表格的 URL 地址栏中，block_id 是下图中高亮部分： image.png - 通过列出仪表盘接口获取
示例值："blknkqrP3RqUkcAW"
数据校验规则：
- 长度范围：0 ～ 100 字符
  └ block_permint是仪表盘的权限
示例值：0
可选值有：
- 0: 无权限 - 1: 可阅读
base_rulemap<string, int>否多维表格点位的权限。更新时，未设置base_rule字段时，所有点位保持旧值。设置base_rule字段为{}时，会将所有点位设置为默认值，即所有点位有权限。 可设置以下两种权限：
- base_complex_edit : 设置是否可以创建副本、下载、打印多维表格 - copy: 设置是否可以复制多维表格内容
该参数类型为 map，其中 key 是权限点位名称，value 是权限开关。value 枚举值有： - 0：无权限 - 1：有权限
注意：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用获取多维表格元数据 查看。
示例值：{"base_complex_edit": 1, "copy": 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": 1
            },
            "other_rec_rule": {
                "conditions": [
                    {
                        "field_name": "单选",
                        "operator": "is",
                        "value": [
                            "optbdVHf4q"
                        ]
                    }
                ],
                "conjunction": "and"
            },
            "field_perm": {
                "姓名": 1,
                "年龄": 2
            },
            "allow_add_record": true,
            "allow_delete_record": true,
            "view_perm": 2,
            "view_rules": {
                "vewEYknYcC": 0
            },
            "field_action_rules": {
                "select_option_edit": {
                    "单选1": 0
                }
            }
        }
    ],
    "block_roles": [
        {
            "block_id": "blknkqrP3RqUkcAW",
            "block_perm": 0
        }
    ],
    "base_rule": {
        "base_complex_edit": 1,
        "copy": 0
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ rolerole自定义角色
    └ role_namestring自定义角色名称
    └ table_rolestable_role\[\]针对数据表的权限设置
      └ table_permint数据表权限。
提示：协作者可编辑自己的记录 和 可编辑指定字段 是 可编辑记录 的特殊情况，可通过指定 rec_rule 或 field_perm 参数实现相同的效果。
可选值有：
- 0: 无权限 - 1: 可阅读 - 2: 可编辑 - 4: 可管理
      └ table_namestring数据表名
      └ table_idstring数据表 ID。详情参考数据表 table。
      └ rec_rulerec_rule记录筛选条件，当 table_perm 为 1 或 2 时生效。用于指定可编辑或可阅读的记录。
        └ conditionsrec_rule_condition\[\]记录筛选条件，用于指定可编辑或可阅读的记录。
          └ field_namestring条件字段的名称。记录筛选条件是“创建人包含访问者本人”时，此参数值为 ""。
          └ operatorstring条件运算符
可选值有：
- is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
          └ valuestring\[\]条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。
          └ field_typeint字段类型
        └ conjunctionstring多个筛选条件的关系
可选值有：
- and: 与 - or: 或
        └ permintrec_rule 的记录对应的权限
可选值有：
- 1: 仅可阅读 - 2: 可编辑
        └ other_permint其他记录权限
可选值有：
- 0: 禁止查看 - 1: 仅可阅读
      └ other_rec_ruleother_rec_rule记录筛选条件，在 rec_rule.other_perm 为 0 时生效。对于未命中 rec_rule 的记录，通过 other_rec_rule 指定可阅读记录范围；此时，既未命中 rec_rule、也未命中 other_rec_rule 的记录会被禁止阅读。
        └ conditionsrec_rule_condition\[\]记录筛选条件
          └ field_namestring字段名
          └ operatorstring运算符
可选值有：
- is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
          └ valuestring\[\]条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。
          └ field_typeint字段类型
        └ conjunctionstring多个筛选条件的关系
可选值有：
- and: 与 - or: 或
        └ permint规则筛选记录对应的权限
可选值有：
- 1: 仅可阅读 - 2: 可编辑
      └ field_permmap<string, int>字段权限，仅在 table_perm 为 2 时有意义，设置字段可编辑或可阅读权限
      └ allow_add_recordboolean新增记录权限，仅在 table_perm 为 2 时有意义，用于设置记录是否可以新增
      └ allow_delete_recordboolean删除记录权限，仅在 table_perm 为 2 时有意义，用于设置记录是否可以删除
      └ view_permint视图权限
可选值有：
- 1: 可阅读 - 2: 可编辑
      └ view_rulesmap<string, int>可读的视图集合，仅在 view_perm 为 1 （视图为可阅读）时生效。 - 未设置时，表示所有视图可读。 - 设置后，表示设置的视图可读，未设置的视图无权限。
该参数类型为 map，其中 key 是视图 ID，value 是视图对应的权限。value 枚举值有： - 0：无权限 - 1：可阅读
      └ field_action_rulesmap<string, map<string, int>>字段点位的权限配置，仅可配置单多选字段、附件字段。点位的枚举值有：
- select_option_edit : 选项配置点位，配置是否可增删改单、多选选项，未设置表示无权限。
- attachment_export: 附件操作权限点位，配置是否可导出附件，未设置表示可导出。
该参数类型为两层 map 结构，其中 key 是字段点位权限，value 是字段权限集合。字段权限集合也是一个 map 结构，其中 key 是字段名称，value 是字段点位权限： - 0：无权限 - 1：有权限
    └ role_idstring自定义权限的id
    └ block_rolesblock_role\[\]block权限
      └ block_idstringBlock ID
      └ block_permintBlock权限
可选值有：
- 0: 无权限 - 1: 可阅读
      └ block_typestringBlock类型
可选值有：
- dashboard: 仪表盘
    └ base_rulemap<string, int>多维表格点位的权限。 - 未设置时，表示自定义角色拥有所有点位权限。 - 设置时，可设置以下两种权限： - base_complex_edit : 设置是否可以创建副本、下载、打印多维表格 - copy: 设置是否可以复制多维表格内容
该参数类型为 map，其中 key 是权限点位名称，value 是权限开关。value 枚举值有： - 0：无权限 - 1：有权限

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "role": {
            "role_name": "自定义权限1",
            "table_roles": [
                {
                    "table_perm": 0,
                    "table_name": "数据表1",
                    "table_id": "tblKz5D60T4JlfcT",
                    "rec_rule": {
                        "conditions": [
                            {
                                "field_name": "单选",
                                "operator": "is",
                                "value": [
                                    "optbdVHf4q"
                                ],
                                "field_type": 3
                            }
                        ],
                        "conjunction": "and",
                        "perm": 1,
                        "other_perm": 1
                    },
                    "other_rec_rule": {
                        "conditions": [
                            {
                                "field_name": "单选",
                                "operator": "is",
                                "value": [
                                    "optbdVHf4q"
                                ],
                                "field_type": 3
                            }
                        ],
                        "conjunction": "and",
                        "perm": 1
                    },
                    "field_perm": {
                        "姓名": 1,
                        "年龄": 2
                    },
                    "allow_add_record": true,
                    "allow_delete_record": true,
                    "view_perm": 2,
                    "view_rules": {
                        "vewEYknYcC": 0
                    },
                    "field_action_rules": {
                        "select_option_edit": {
                            "单选1": 0
                        }
                    }
                }
            ],
            "role_id": "roljRpwIUt",
            "block_roles": [
                {
                    "block_id": "blknkqrP3RqUkcAW",
                    "block_perm": 0,
                    "block_type": "dashboard"
                }
            ],
            "base_rule": {
                "duplicate": 1,
                "copy": 2
            }
        }
    }
}

错误码 ​

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自定义角色名重复
4001254036Bitable 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请求过快，稍后重试
4001254301OperationTypeError多维表格未开启高级权限或不支持开启高级权限
4031254304Only Available For Business and Enterprise Editions仅企业版和旗舰版飞书支持行列权限
2001255001InternalError内部错误，请联系技术支持
2001255002Something went wrong. Please contact technical support at https://applink.feishu.cn/client/helpdesk/open?id=6626260912531570952Something went wrong. Please contact technical support at https://applink.feishu.cn/client/helpdesk/open?id=6626260912531570952
2001255003MarshalError序列化错误，请联系技术支持
2001255004UmMarshalError反序列化错误，请联系技术支持
5041255040Request timed out, please try again later请求超时，进行重试

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

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