飞书开放平台 Server API 文档

主题

列出自定义角色(新版) ​

列出多维表格高级权限中用户自定义的角色。

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

前提条件 ​

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

请求 ​

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

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数 ​

名称类型描述
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 字符

查询参数 ​

名称类型必填描述
page_sizeint否分页大小
示例值：10
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：roljRpwIUt

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemsrole\[\]自定义角色列表
    └ role_namestring自定义权限的名字
    └ table_rolestable_role\[\]数据表权限列表
      └ table_permint数据表权限
可选值有：
- 0: 无权限 - 1: 可阅读 - 2: 可编辑 - 4: 可管理
      └ table_namestring数据表名
      └ table_idstring数据表ID
      └ 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: 或
        └ permint规则筛选记录对应的权限
可选值有：
- 1: 仅可阅读 - 2: 可编辑
        └ other_permint其他记录权限，仅在 table_perm 为 2 （数据表权限为可编辑）时生效。 - 当 other_perm 为 1 时，表示未命中 rec_rule 的记录仅可阅读，不可编辑 - 当 other_perm 为 0 时，表示既未命中 rec_rule、也未命中 other_rec_rule 的记录会被禁止阅读。即你可以通过 other_rec_rule 进一步指定可阅读的记录范围。
可选值有：
- 0: 禁止查看 - 1: 仅可阅读
        └ condition_groupscondition_group\[\]条件组
          └ condition_typeint条件组类型
可选值有：
- 1: 单个条件 - 2: 条件组
          └ conditionsrec_rule_condition\[\]条件列表
            └ field_namestring字段名
            └ operatorstring运算符
可选值有：
- is: 等于 - isNot: 不等于 - contains: 包含 - doesNotContain: 不包含 - isEmpty: 为空 - isNotEmpty: 不为空
            └ valuestring\[\]单选或多选字段的选项id
            └ field_typeint字段类型
          └ conjunctionstring条件符
可选值有：
- and: 满足所有条件 - or: 满足任一条件
        └ display_rec_rule_versionint条件版本
可选值有：
- 0: 仅支持条件 - 1: 支持条件组
      └ other_rec_ruleother_rec_rule记录筛选条件，在 rec_rule.Perm 为 2 时有意义，用于指定剩余可阅读的记录。
        └ 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 为 1和 2 时生效。用于设置字段可编辑或可阅读。类型为 map，key 是字段名称，value 是字段权限。对于未设置的字段，默认无权限。value 枚举值有： - 1：可阅读 - 2：可添加 - 3：可编辑
      └ 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：有权限
注意：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用获取多维表格元数据 查看。
    └ 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：有权限
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项
  └ totalint总数

响应体示例 ​

json
{"code":0,
"msg":"success",
"data":{"items":[{"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,
"condition_groups":[{"condition_type":and,
"conditions":[{
    "field_name": "单选",
    "operator": "is",
    "value": [
        "optbdVHf4q"
    ],
    "field_type": 3
}],
"conjunction":"or"}],
"display_rec_rule_version":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}}],
"page_token":"eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=",
"has_more":true,
"total":1}}

错误码 ​

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多维表格未开启高级权限或不支持开启高级权限
2001255001InternalError内部错误，请联系技术支持
2001255002Something 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请求超时，进行重试

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

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