# 列出自定义角色(新版) 列出多维表格高级权限中用户自定义的角色。 **注意事项**：相较于旧版接口，新版自定义角色接口支持高级权限 2.0 版本新增的权限点位，包括更精细的行级别权限控制、多维表格的复制、导出点位的控制等。 ## 前提条件 要调用自定义角色相关接口，你需确保多维表格已开启高级权限。你可通过[更新多维表格元数据](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app/update)接口开启高级权限。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/base/v2/apps/:app_token/roles HTTP Method | GET 接口频率限制 | [20 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 查询自定义角色(base:role:read) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) ### 路径参数 名称 | 类型 | 描述 ---|---|--- app_token | string | 多维表格 App 的唯一标识。不同形态的多维表格，其 `app_token` 的获取方式不同：
- 如果多维表格的 URL 以 ==**feishu.cn/base**== 开头，该多维表格的 `app_token` 是下图高亮部分：
![app_token.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/6916f8cfac4045ba6585b90e3afdfb0a_GxbfkJHZBa.png?height=766&lazyload=true&width=3004)
- 如果多维表格的 URL 以 ==**feishu.cn/wiki**== 开头，你需调用知识库相关[获取知识空间节点信息](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/wiki-v2/space/get_node)接口获取多维表格的 app_token。当 `obj_type` 的值为 `bitable` 时，`obj_token` 字段的值才是多维表格的 `app_token`。
了解更多，参考[多维表格 app_token 获取方式](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/bitable-overview#-752212c)。
**示例值**："appbcbWCzen6D8dezhoCH2RpMAh"
**数据校验规则**：
- 长度范围：`0` ～ `100` 字符 ### 查询参数 名称 | 类型 | 必填 | 描述 ---|---|---|--- page_size | int | 否 | 分页大小
**示例值**：10 page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
**示例值**：roljRpwIUt ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- items | role\[\] | 自定义角色列表 role_name | string | 自定义权限的名字 table_roles | table_role\[\] | 数据表权限列表 table_perm | int | 数据表权限
**可选值有**：
- 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）填写说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/record-filter-guide#3e0fd644)。 field_type | int | 字段类型 conjunction | string | 多个筛选条件的关系
**可选值有**：
- and：与
- or：或 perm | int | 规则筛选记录对应的权限
**可选值有**：
- 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：仅可阅读 condition_groups | condition_group\[\] | 条件组 condition_type | int | 条件组类型
**可选值有**：
- 1：单个条件
- 2：条件组 conditions | rec_rule_condition\[\] | 条件列表 field_name | string | 字段名 operator | string | 运算符
**可选值有**：
- is：等于
- isNot：不等于
- contains：包含
- doesNotContain：不包含
- isEmpty：为空
- isNotEmpty：不为空 value | string\[\] | 单选或多选字段的选项id field_type | int | 字段类型 conjunction | string | 条件符
**可选值有**：
- and：满足所有条件
- or：满足任一条件 display_rec_rule_version | int | 条件版本
**可选值有**：
- 0：仅支持条件
- 1：支持条件组 other_rec_rule | other_rec_rule | 记录筛选条件，在 rec_rule.Perm 为 2 时有意义，用于指定剩余可阅读的记录。 conditions | rec_rule_condition\[\] | 记录筛选条件 field_name | string | 字段名 operator | string | 运算符
**可选值有**：
- is：等于
- isNot：不等于
- contains：包含
- doesNotContain：不包含
- isEmpty：为空
- isNotEmpty：不为空 value | string\[\] | 条件的值，可以是单个值或多个值的数组。详情参考[字段目标值（value）填写说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-table-record/record-filter-guide#3e0fd644)。 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](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/bitable-overview#5b05b8ca)，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`：有权限
**注意**：仅高级权限为 v2 版本的多维表格支持该参数。是否是 v2 版本可调用[获取多维表格元数据
](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app/get)查看。 role_id | string | 自定义权限的 ID block_roles | block_role\[\] | block权限 block_id | string | Block ID block_perm | int | Block权限
**可选值有**：
- 0：无权限
- 1：可阅读 block_type | string | Block类型
**可选值有**：
- dashboard：仪表盘 base_rule | map<string, int> | 多维表格点位的权限。
- 未设置时，表示自定义角色拥有所有点位权限。
- 设置时，可设置以下两种权限：
- `base_complex_edit` : 设置是否可以创建副本、下载、打印多维表格
- `copy`: 设置是否可以复制多维表格内容
该参数类型为 map，其中 key 是权限点位名称，value 是权限开关。value 枚举值有：
- `0`：无权限
- `1`：有权限 page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token has_more | boolean | 是否还有更多项 total | int | 总数 ### 响应体示例 ```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状态码 | 错误码 | 描述 | 排查建议 ---|---|---|--- 200 | 1254000 | WrongRequestJson | 请求体错误 200 | 1254001 | WrongRequestBody | 请求体错误 200 | 1254002 | Fail | 导致报 1254002 错误码的场景较多，请参考以下建议排查：
- 如果单次操作的内容变更较大，请尝试在单次操作中减少数据量
- 如果你并发调用了接口，请尝试控制请求间隔，稍后重试
- 如果在知识库（wiki）中创建多维表格，请检查你是否使用了知识库[创建知识空间节点](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/wiki-v2/space-node/create)接口创建多维表格。在此场景下不能使用[创建多维表格](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app/create)接口
- 请检查接口参数是否有误。例如，在分页查询多维表格时，传递了无效的 page_token，或传递了错误的数据表的 table_id
- 如果该报错偶尔发生，可能是服务器超时或不稳定，请重试解决 200 | 1254003 | WrongBaseToken | app_token 错误。app_token 是多维表格 App 的唯一标识。不同形态的多维表格，其 `app_token` 的获取方式不同：
- 如果多维表格的 URL 以 ==**feishu.cn/base**== 开头，该多维表格的 `app_token` 是下图高亮部分：
![app_token.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/6916f8cfac4045ba6585b90e3afdfb0a_GxbfkJHZBa.png?height=766&lazyload=true&width=3004)
- 如果多维表格的 URL 以 ==**feishu.cn/wiki**== 开头，你需调用知识库相关[获取知识空间节点信息](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/wiki-v2/space/get_node)接口获取多维表格的 app_token。当 `obj_type` 的值为 `bitable` 时，`obj_token` 字段的值才是多维表格的 `app_token`。
了解更多，参考[多维表格 app_token 获取方式](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/bitable-overview#-752212c)。 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` 是下图高亮部分：
![app_token.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/6916f8cfac4045ba6585b90e3afdfb0a_GxbfkJHZBa.png?height=766&lazyload=true&width=3004)
- 如果多维表格的 URL 以 ==**feishu.cn/wiki**== 开头，你需调用知识库相关[获取知识空间节点信息](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/wiki-v2/space/get_node)接口获取多维表格的 app_token。当 `obj_type` 的值为 `bitable` 时，`obj_token` 字段的值才是多维表格的 `app_token`。
了解更多，参考[多维表格 app_token 获取方式](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/bitable-overview#-752212c)。 404 | 1254047 | RoleIdNotFound | role_id 不存在。role_id 是多维表格高级权限中自定义角色的唯一标识，以 `rol` 开头。可通过[列出自定义角色](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/bitable-v1/app-role/list)接口获取。 400 | 1254110 | RoleExceedLimit | 自定义角色数量超限，限制 30 条 200 | 1254290 | TooManyRequest | 请求过快，稍后重试 400 | 1254301 | OperationTypeError | 多维表格未开启高级权限或不支持开启高级权限 200 | 1255001 | InternalError | 内部错误，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW) 200 | 1255002 | Something went wrong. Please contact technical support at https://applink.feishu.cn/client/helpdesk/open?id=6626260912531570952 | 内部错误，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW) 200 | 1255003 | MarshalError | 序列化错误，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW) 200 | 1255004 | UmMarshalError | 反序列化错误，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW) 504 | 1255040 | Request timed out, please try again later | 请求超时，进行重试