# 根据角色查询人员信息 - getUserInfosByRole #### 功能介绍 本接口用于根据角色信息查询流程引擎中的用户信息，支持按团队角色、用户组角色或系统角色进行筛选，适用于快速定位流程审批链中的相关人员，实现基于角色的任务分配和权限管控。与[查询人员信息 - getUserInfos](https://support.huaweicloud.com/api-idme/getUserInfos.html)接口配合，可先通过用户名精确查询，再通过角色批量筛选；与[启动流程 - startProcessInstance](https://support.huaweicloud.com/api-idme/startProcessInstance.html)接口配合，可按角色批量配置流程参与者。 #### 接口约束 - 本接口支持基础版和体验版数据建模引擎-流程引擎场景。 - 角色查询支持三种维度组合使用：团队角色（teamAndTeamRoleXdmId）、用户组角色（userGroupXdmId）、系统角色（roleXdmId）。至少需传入一种角色维度，否则将返回空结果。 - "userCn"参数为可选的辅助筛选条件，传入后将同时在角色匹配结果中按用户名模糊过滤。 - 分页参数"pageSize"和"curPage"需同时传入才生效，仅传其一可能导致分页异常。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-idme/idme_api_0003.html)。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-idme/idme_api_0017.html)。 - 如果使用身份策略授权，当前API调用无需身份策略权限。 #### URI POST /console/servicetask/api/localMethod/participant/getUserInfosByRole #### 请求参数 表1请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释：** IAM用户的token。 通过调用IAM服务[获取用户Token](https://support.huaweicloud.com/api-iam/iam_30_0001.html)接口获取（即响应消息头中X-Subject-Token的值）。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | X-Application-Id | 是 | String | **参数解释：** 应用ID。 您可以在应用设计态的"应用中心 \> 应用发布"页面获取，详情请参见[应用发布](https://support.huaweicloud.com/usermanual-idme/idme_usermanual_0085.html)。 **约束限制：** 不涉及。 **取值范围：** 由英文字母和数字组成，且长度为32个字符。 **默认取值：** 不涉及。 | | X-Tenant-Id | 是 | String | **参数解释：** 数据建模引擎运行态租户ID。 您可以从访问流程引擎编排服务的浏览器地址栏中获取。 流程编排服务地址：http://{承载流程编排服务的服务器域名或IP地址}:{流程编排服务的端口号}/{流程编排服务文根}/index.html#/processApplicationForm?tenantId={数据建模引擎运行态租户ID}\&applicationId={应用ID} 例如tenantId=-1，表示数据建模引擎运行态默认租户"basicTenant"的租户ID为-1。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | X-User-Id | 是 | String | **参数解释：** 请求当前接口时上下文中的用户ID，即OrgID的用户ID。 通过调用OrgID服务的[获取用户信息](https://support.huaweicloud.com/api-orgid/ShowOauth2UserInfo.html)接口获取。 **约束限制：** 仅基础版数据建模引擎-流程引擎需要配置此参数。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | userCn | 否 | String | **参数解释：** 用户中文名，用于在角色匹配结果中按用户名进行模糊筛选。传入后将缩小返回范围，仅保留用户名包含该字符串的用户。 **约束限制：** 不涉及。 **取值范围：** 最大长度500字符。 **默认取值：** 不涉及。 | | pageSize | 否 | String | **参数解释：** 每页显示的记录数，用于分页查询时控制单页数据量。需与"curPage"同时传入才生效。 **约束限制：** 建议不超过100，过大的分页值可能影响接口性能。 **取值范围：** 正整数，取值范围1-100。 **默认取值：** 不传则不启用分页，返回所有结果。 | | curPage | 否 | String | **参数解释：** 当前页码，用于指定分页查询的页数。需与"pageSize"同时传入才生效，从1开始计数。 **约束限制：** 不涉及。 **取值范围：** 正整数，从1开始。 **默认取值：** 不传则不启用分页。 | | agentUserQueryVo | 否 | Array of [AgentUserQueryVo] objects | **参数解释：** 角色查询条件对象，用于指定需要查询的角色标识集合，支持团队角色、用户组角色和系统角色三种维度。 **约束限制：** 至少需传入一种角色维度，否则返回空结果。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表3AgentUserQueryVo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | isAuto | 否 | Boolean | **参数解释：** 是否自动带出参与人（即流程运行时是否自动根据角色/群组/团队查询并填充处理人）。 **约束限制：** 不涉及。 **取值范围：** - true：自动带出。 - false：手动选择。 **默认取值：** false。 | | roleXdmId | 否 | Array of strings | **参数解释：** 系统角色ID列表，用于按系统角色筛选用户。系统角色为全局角色，不局限于特定团队或用户组。 **约束限制：** 与"teamAndTeamRoleXdmId"、"userGroupXdmId"至少传入一个。 **取值范围：** 角色ID数组，每个ID为字符串类型。 **默认取值：** 空数组\[\]。 | | teamAndTeamRoleXdmId | 否 | Array of strings | **参数解释：** 团队角色ID列表，用于按团队及团队内角色筛选用户。团队角色为特定组织架构下的角色，如"研发部-经理"。 **约束限制：** 与"roleXdmId"、"userGroupXdmId"至少传入一个。 **取值范围：** 团队角色ID数组，每个ID为字符串类型。 **默认取值：** 空数组\[\]。 | | userGroupXdmId | 否 | Array of strings | **参数解释：** 用户组角色ID列表，用于按用户组筛选用户。用户组为跨团队的虚拟分组，如"质量审核小组"。 **约束限制：** 与"roleXdmId"、"teamAndTeamRoleXdmId"至少传入一个。 **取值范围：** 用户组ID数组，每个ID为字符串类型。 **默认取值：** 空数组\[\]。 | #### 响应参数 **状态码：200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | code | Integer | **参数解释：** 接口返回码，标识接口调用的执行结果。 **取值范围：** - 0：成功。 - 非0：失败，具体错误码请参见[错误码](https://support.huaweicloud.com/api-idme/WorkFlow-Engine-ErrorCode.html)。 | | data | [data] object | **参数解释：** 接口响应数据，包含用户信息列表和分页信息。 **取值范围：** 不涉及。 | | orderID | String | **参数解释：** 请求跟踪流水号，用于唯一标识本次接口请求，便于问题排查和链路追踪。 遇到问题时，请提供此ID联系技术支持。 **取值范围：** 不涉及。 | 表5data | 参数 | 参数类型 | 描述 | |:---|:---|:---| | userInfoList | Array of [UserInfoVo] objects | **参数解释：** 查询到的用户信息列表。如未找到匹配用户，返回空数组\[\]。 **取值范围：** 不涉及。 | | pageInfo | [PageVo] object | **参数解释：** 标准响应体分页信息，包含当前页、页大小、总页数等。 **取值范围：** 不涉及。 | 表6UserInfoVo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | accountStatus | String | **参数解释：** 账号状态，标识用户账号的当前可用状态。调用方需根据此字段过滤不可用用户。 **取值范围：** - 1：正常，账号可用。 - 0：账号状态异常，账号不可用（如已停用、已锁定等）。 | | ucn | String | **参数解释：** 用户名中文名（User Chinese Name），用于展示用户的可读名称。与查询参数"userCn"匹配时返回此字段值。 **取值范围：** 不涉及。 | | uid | String | **参数解释：** 用户标识（User ID），通常与"ucn"值一致，用于系统内部用户标识。 **取值范围：** 不涉及。 | | uuid | String | **参数解释：** 用户唯一标识（Universally Unique Identifier），用于在分布式系统中唯一标识用户。此字段为启动流程时"participant"区块配置参与者的关键字段。 **取值范围：** 不涉及。 | | account | String | **参数解释：** 账号名，用于用户登录系统的账户标识。通常与"ucn"值一致。 **取值范围：** 不涉及。 | 表7PageVo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | totalRows | Integer | **参数解释：** 数据总数，标识符合条件的流程实例总记录数。 **取值范围：** 非负整数。 | | curPage | Integer | **参数解释：** 当前页码，与请求参数中的curPage一致。 **取值范围：** 正整数。 | | pageSize | Integer | **参数解释：** 页大小，与请求参数中的pageSize一致。 **取值范围：** 正整数。 | | totalPages | Integer | **参数解释：** 总页数，根据totalRows和pageSize计算得出的总页数。计算公式为ceil(totalRows / pageSize)。 **取值范围：** 不涉及。 | **状态码：400** 表8响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 错误码。 | | error_msg | String | 错误描述。 | | result | String | 结果。 | | trace_id | String | 追踪ID。 | #### 请求示例 ``` POST https://dme.cn-north-4.huaweicloud.cn/workflowRuntime/console/servicetask/api/localMethod/participant/getUserInfosByRole { "agentUserQueryVo" : { "isAuto" : false, "teamAndTeamRoleXdmId" : [ ], "userGroupXdmId" : [ ], "roleXdmId" : [ "111", "222" ] }, "userCN" : "hid_fje4j2nvnue3xwp", "pageSize" : 10, "curPage" : 1 } ``` #### 响应示例 **状态码：200** OK ``` { "code" : 0, "data" : { "userInfoList" : [ { "accountStatus" : "1", "ucn" : "test1 est", "uid" : "test1", "uuid" : "1008600000011635080" } ], "pageInfo" : { "curPage" : 1, "totalPages" : 1, "pageSize" : 10 } }, "orderID" : 1008600000011635080 } ``` **状态码：400** Bad Request ``` { "error_code" : "500", "error_msg" : "origin is not allowed!", "result" : "FAIL", "trace_id" : "2509bee60b3e40asdf9f741d9e23466a9" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | OK | | 400 | Bad Request | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-idme/WorkFlow-Engine-ErrorCode.html)。