新增自定义角色(新版)

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

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

前提条件

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

请求

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

请求头

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

路径参数

名称	类型	描述
app_token	string	多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： - 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。 了解更多，参考多维表格 app_token 获取方式。 示例值："appbcbWCzen6D8dezhoCH2RpMAh" 数据校验规则： - 长度范围：0 ～ 100 字符

请求体

名称	类型	必填	描述
role_name	string	是	自定义权限的名字 示例值："普通用户" 数据校验规则： - 长度范围：0 ～ 100 字符
table_roles	table_role\[\]	是	针对数据表的权限设置 数据校验规则： - 长度范围：0 ～ 100
└ table_perm	int	是	数据表权限。 提示：协作者可编辑自己的记录 和 可编辑指定字段 是 可编辑记录 的特殊情况，可通过指定 rec_rule 或 field_perm 参数实现相同的效果。 示例值：0 可选值有： - 0: 无权限 - 1: 仅可阅读 - 2: 可编辑 - 4: 可管理 数据校验规则： - 取值范围：0 ～ 4
└ table_name	string	否	数据表名称（与下方 table_id 至少填写一项）。 示例值："数据表1" 数据校验规则： - 长度范围：0 ～ 50 字符
└ table_id	string	否	多维表格数据表的唯一标识。（与上方 table_name 至少填写一项）。获取方式： - 你可通过多维表格 URL 获取 table_id，下图高亮部分即为当前数据表的 table_id - 也可通过列出数据表接口获取 table_id 示例值："tblKz5D60T4JlfcT" 数据校验规则： - 长度范围：0 ～ 50 字符
└ rec_rule	rec_rule	否	记录筛选条件，当 table_perm 为 1 或 2 时生效。用于指定可编辑或可阅读的记录。
└ conditions	rec_rule_condition\[\]	否	记录筛选条件，用于指定可编辑或可阅读的记录。 数据校验规则： - 长度范围：0 ～ 10
└ field_name	string	是	条件字段的名称。记录筛选条件是“创建人包含访问者本人”时，此参数值为 ""。 示例值："单选"
└ operator	string	否	条件运算符 示例值："is" 可选值有： - is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空 默认值：is
└ value	string\[\]	否	条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。 示例值：["optbdVHf4q"] 数据校验规则： - 长度范围：0 ～ 50
└ conjunction	string	否	多个筛选条件的关系 示例值："and" 可选值有： - and: 与 - or: 或 默认值：and
└ other_perm	int	否	其他记录权限，仅在 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_rule	other_rec_rule	否	记录筛选条件，在 rec_rule.other_perm 为 0 时生效。对于未命中 rec_rule 的记录，通过 other_rec_rule 指定可阅读记录范围；此时，既未命中 rec_rule、也未命中 other_rec_rule 的记录会被禁止阅读。 注意：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用获取多维表格元数据 查看。
└ conditions	rec_rule_condition\[\]	否	记录筛选条件，用于指定可阅读的记录。 数据校验规则： - 长度范围：0 ～ 10
└ field_name	string	是	条件字段的名称。记录筛选条件是“创建人包含访问者本人”时，此参数值为 ""。 示例值："单选"
└ operator	string	否	条件运算符 示例值："is" 可选值有： - is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空 默认值：is
└ value	string\[\]	否	条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。 示例值：["optbdVHf4q"] 数据校验规则： - 长度范围：0 ～ 50
└ conjunction	string	否	多个筛选条件的关系 示例值："and" 可选值有： - and: 与 - or: 或 默认值：and
└ field_perm	map<string, int>	否	字段权限，仅在 table_perm 为 1和 2 时生效。用于设置字段可编辑或可阅读。类型为 map，key 是字段名称，value 是字段权限。对于未设置的字段，默认无权限。value 枚举值有： - 1：可阅读 - 2：可添加 - 3：可编辑 示例值：{"姓名": 1, "年龄": 2}
└ allow_add_record	boolean	否	新增记录权限，仅在 table_perm 为 2 时生效，用于设置记录是否可以新增。 示例值：true 默认值：true
└ allow_delete_record	boolean	否	删除记录权限，仅在 table_perm 为 2 时生效，用于设置记录是否可以删除。 示例值：true 默认值：true
└ view_perm	int	否	设置视图的权限。 示例值：2 可选值有： - 1: 可阅读 - 2: 可编辑 默认值：2 数据校验规则： - 取值范围：0 ～ 2
└ view_rules	map<string, int>	否	可读的视图集合，仅在 view_perm 为 1 （视图为可阅读）时生效。 - 未设置时，表示所有视图可读。 - 设置后，表示设置的视图可读，未设置的视图无权限。 该参数类型为 map，其中 key 是视图 ID，value 是视图对应的权限。value 枚举值有： - 0：无权限 - 1：可阅读 注意：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用获取多维表格元数据 查看。 示例值：{"vewEYknYcC": 0}
└ field_action_rules	map<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_roles	block_role\[\]	否	针对仪表盘的权限设置 数据校验规则： - 长度范围：0 ～ 100
└ block_id	string	是	多维表格仪表盘的唯一标识，以 blk 开头。获取方式： - 在多维表格的 URL 地址栏中，block_id 是下图中高亮部分： - 通过列出仪表盘接口获取 示例值："blknkqrP3RqUkcAW" 数据校验规则： - 长度范围：0 ～ 100 字符
└ block_perm	int	是	设置仪表盘的权限 示例值：0 可选值有： - 0: 无权限 - 1: 可阅读
base_rule	map<string, int>	否	多维表格点位的权限。 - 未设置时，表示自定义角色拥有所有点位权限。 - 设置时，可设置以下两种权限： - base_complex_edit : 设置是否可以创建副本、下载、打印多维表格 - copy: 设置是否可以复制多维表格内容 该参数类型为 map，其中 key 是权限点位名称，value 是权限开关。value 枚举值有： - 0：无权限 - 1：有权限 注意：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用获取多维表格元数据 查看。 示例值：{"base_complex_edit": 1, "copy": 0}

请求体示例

{
    "role_name": "普通用户",
    "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
    }
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ role	role	自定义角色
└ role_name	string	自定义角色名称
└ table_roles	table_role\[\]	针对数据表的权限设置
└ table_perm	int	数据表权限。 提示：协作者可编辑自己的记录 和 可编辑指定字段 是 可编辑记录 的特殊情况，可通过指定 rec_rule 或 field_perm 参数实现相同的效果。 可选值有： - 0: 无权限 - 1: 可阅读 - 2: 可编辑 - 4: 可管理
└ table_name	string	数据表名称
└ table_id	string	数据表 ID
└ rec_rule	rec_rule	记录筛选条件，当 table_perm 为 1 或 2 时生效。用于指定可编辑或可阅读的记录。
└ conditions	rec_rule_condition\[\]	记录筛选条件，用于指定可编辑或可阅读的记录。
└ field_name	string	条件字段的名称。
└ operator	string	条件运算符 可选值有： - is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
└ value	string\[\]	条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。
└ field_type	int	字段类型
└ conjunction	string	多个筛选条件的关系 可选值有： - and: 与 - or: 或
└ perm	int	命中 rec_rule 的记录对应的权限，可不设置，理论上应该与 table_perm 保持一致 可选值有： - 1: 仅可阅读 - 2: 可编辑
└ other_perm	int	其他记录权限，仅在 table_perm 为 2 （数据表权限为可编辑）时生效。 - 当 other_perm 为 1 时，表示未命中 rec_rule 的记录仅可阅读，不可编辑 - 当 other_perm 为 0 时，表示既未命中 rec_rule、也未命中 other_rec_rule 的记录会被禁止阅读。即你可以通过 other_rec_rule 进一步指定可阅读的记录范围。 可选值有： - 0: 禁止查看 - 1: 仅可阅读
└ other_rec_rule	other_rec_rule	记录筛选条件，在 rec_rule.other_perm 为 0 时生效。对于未命中 rec_rule 的记录，通过 other_rec_rule 指定可阅读记录范围；此时，既未命中 rec_rule、也未命中 other_rec_rule 的记录会被禁止阅读。
└ conditions	rec_rule_condition\[\]	记录筛选条件，用于指定可阅读的记录。
└ field_name	string	条件字段的名称。记录筛选条件是“创建人包含访问者本人”时，此参数值为 ""。
└ operator	string	条件运算符 可选值有： - is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
└ value	string\[\]	条件的值，可以是单个值或多个值的数组。详情参考字段目标值（value）填写说明。
└ field_type	int	字段类型
└ conjunction	string	多个筛选条件的关系 可选值有： - and: 与 - or: 或
└ perm	int	规则筛选记录对应的权限 可选值有： - 1: 仅可阅读 - 2: 可编辑
└ field_perm	map<string, int>	字段权限，仅在 table_perm 为 1 和 2 时生效。用于设置字段的可编辑或可阅读权限。类型为 map，key 是字段名称，value 是字段权限。value 枚举值有： - 1：可阅读 - 2：可添加 - 3：可编辑
└ allow_add_record	boolean	新增记录权限，仅在 table_perm 为 2 时生效，用于设置记录是否可以新增。
└ allow_delete_record	boolean	删除记录权限，仅在 table_perm 为 2 时生效，用于设置记录是否可以删除。
└ view_perm	int	视图权限 可选值有： - 1: 可阅读 - 2: 可编辑
└ view_rules	map<string, int>	可读的视图集合，仅在 view_perm 为 1 （视图为可阅读）时生效。 - 未设置时，表示所有视图可读。 - 设置后，表示设置的视图可读，未设置的视图无权限。 该参数类型为 map，其中 key 是视图 ID，value 是视图对应的权限。value 枚举值有： - 0：无权限 - 1：可阅读
└ field_action_rules	map<string, map<string, int>>	字段点位的权限配置，仅可配置单多选字段、附件字段。点位的枚举值有： - select_option_edit : 选项配置点位，配置是否可增删改单、多选选项，未设置表示无权限。 - attachment_export: 附件操作权限点位，配置是否可导出附件，未设置表示可导出。 该参数类型为两层 map 结构，其中 key 是字段点位权限，value 是字段权限集合。字段权限集合也是一个 map 结构，其中 key 是字段名称，value 是字段点位权限： - 0：无权限 - 1：有权限
└ role_id	string	自定义权限的 ID
└ block_roles	block_role\[\]	针对仪表盘的权限设置
└ block_id	string	多维表格仪表盘的唯一标识
└ block_perm	int	仪表盘的权限 可选值有： - 0: 无权限 - 1: 可阅读
└ block_type	string	仪表盘类型 可选值有： - dashboard: 仪表盘
└ base_rule	map<string, int>	多维表格点位的权限。 - 未设置时，表示自定义角色拥有所有点位权限。 - 设置时，可设置以下两种权限： - base_complex_edit : 设置是否可以创建副本、下载、打印多维表格 - copy: 设置是否可以复制多维表格内容 该参数类型为 map，其中 key 是权限点位名称，value 是权限开关。value 枚举值有： - 0：无权限 - 1：有权限

响应体示例

{
    "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": {
                "base_complex_edit": 1,
                "copy": 0
            }
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
200	1254000	WrongRequestJson	请求体错误
200	1254001	WrongRequestBody	请求体错误
200	1254002	Fail	导致报 1254002 错误码的场景较多，请参考以下建议排查： - 如果单次操作的内容变更较大，请尝试在单次操作中减少数据量 - 如果你并发调用了接口，请尝试控制请求间隔，稍后重试 - 如果在知识库（wiki）中创建多维表格，请检查你是否使用了知识库创建知识空间节点接口创建多维表格。在此场景下不能使用创建多维表格接口 - 请检查接口参数是否有误。例如，在分页查询多维表格时，传递了无效的 page_token，或传递了错误的数据表的 table_id - 如果该报错偶尔发生，可能是服务器超时或不稳定，请重试解决
200	1254003	WrongBaseToken	app_token 错误。app_token 是多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： - 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。 了解更多，参考多维表格 app_token 获取方式。
200	1254010	ReqConvError	请求错误
400	1254032	InvalidRoleName	自定义角色名无效
400	1254033	RoleNameDuplicated	自定义角色名重复
400	1254036	Bitable is copying, please try again later.	复制多维表格为异步操作，该错误码表示当前多维表格仍在复制中，在复制期间无法操作当前多维表格。需要等待复制完成后再操作
200	1254040	BaseTokenNotFound	app_token 不存在。app_token 是多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： - 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。 了解更多，参考多维表格 app_token 获取方式。
404	1254047	RoleIdNotFound	role_id 不存在。role_id 是多维表格高级权限中自定义角色的唯一标识，以 rol 开头。可通过列出自定义角色接口获取。
400	1254110	RoleExceedLimit	自定义角色数量超限，限制 30 条
200	1255002	Something went wrong. Please contact technical support at https://applink.feishu.cn/client/helpdesk/open?id=6626260912531570952	内部错误，请联系技术支持
200	1254290	TooManyRequest	请求过快，稍后重试
400	1254301	OperationTypeError	多维表格未开启高级权限或不支持开启高级权限
403	1254304	Only Available For Business and Enterprise Editions	仅企业版和旗舰版飞书支持行列权限
200	1255001	InternalError	内部错误，请联系技术支持
200	1255003	MarshalError	序列化错误，请联系技术支持
200	1255004	UmMarshalError	反序列化错误，请联系技术支持
504	1255040	Request timed out, please try again later	请求超时，进行重试