查询企业角色列表

1. 接口描述

接口请求域名： ess.tencentcloudapi.com 。

此接口（DescribeIntegrationRoles）用于分页查询企业角色列表，列表按照角色创建时间升序排列。

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer

点击调试

API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeIntegrationRoles。
Version	是	String	公共参数，本接口取值：2020-11-11。
Region	否	String	公共参数，此参数为可选参数。
Operator	是	UserInfo	执行本接口操作的员工信息。使用此接口时，必须填写UserId。 注: `在调用此接口时，请确保指定的员工已获得所需的接口调用权限，并具备接口传入的相应资源的数据权限。
Limit	是	Integer	指定分页每页返回的数据条数，单页最大支持 200。
Agent	否	Agent	代理企业和员工的信息。 在集团企业代理子企业操作的场景中，需设置此参数。在此情境下，ProxyOrganizationId（子企业的组织ID）为必填项。
Filters.N	否	Array of Filter	查询的关键字段，支持Key-Value单值查询。可选键值对如下： Key:"RoleType"，查询角色类型，Values可选： "1"：查询系统角色 "2"：查询自定义角色 Key:"RoleStatus"，查询角色状态，Values可选： "1"：查询启用角色 "2"：查询禁用角色 Key:"IsGroupRole"，是否查询集团角色，Values可选： "0"：查询非集团角色 "1"：查询集团角色 Key:"IsReturnPermissionGroup"，是否返回角色对应权限树，Values可选： "0"：接口不返回角色对应的权限树字段 "1"：接口返回角色对应的权限树字段
Offset	否	Integer	OFFSET 用于指定查询结果的偏移量，如果不传默认偏移为0,最大2000。 分页参数, 需要limit, offset 配合使用 例如: 您希望得到第三页的数据, 且每页限制最多10条 您可以使用 LIMIT 10 OFFSET 20

3. 输出参数

参数名称	类型	描述
Offset	Integer	OFFSET 用于指定查询结果的偏移量，如果不传默认偏移为0, 最大为2000 分页参数, 需要limit, offset 配合使用 例如: 您希望得到第三页的数据, 且每页限制最多10条 您可以使用 LIMIT 10 OFFSET 20 示例值：1
Limit	Integer	指定分页每页返回的数据条数，单页最大支持 200。 示例值：20
TotalCount	Integer	符合查询条件的总角色数。 示例值：10
IntegrateRoles	Array of IntegrateRole	企业角色信息列表。
RequestId	String	唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 示例-主代子查询

示例-主代子查询

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationRoles
<公共请求参数>

{
    "Filters": [
        {
            "Key": "RoleType",
            "Values": [
                "1"
            ]
        }
    ],
    "Agent": {
        "ProxyOrganizationId": "y**********************J"
    },
    "Operator": {
        "UserId": "y******************5"
    },
    "Limit": 1,
    "Offset": 0
}

输出示例

{
    "Response": {
        "IntegrateRoles": [
            {
                "IsGroupRole": false,
                "RoleId": "c*************************b",
                "RoleName": "超级管理员",
                "RoleStatus": 1,
                "SubOrgIdList": []
            }
        ],
        "Limit": 1,
        "Offset": 0,
        "RequestId": "s************************1",
        "TotalCount": 8
    }
}

示例2 示例-普通企业查询

示例-普通企业查询

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationRoles
<公共请求参数>

{
    "Filters": [
        {
            "Key": "RoleType",
            "Values": [
                "1"
            ]
        }
    ],
    "Operator": {
        "UserId": "y******************5"
    },
    "Limit": 5,
    "Offset": 0
}

输出示例

{
    "Response": {
        "IntegrateRoles": [
            {
                "IsGroupRole": false,
                "RoleId": "b4******************bf",
                "RoleName": "超级管理员",
                "RoleStatus": 1,
                "SubOrgIdList": []
            },
            {
                "IsGroupRole": false,
                "RoleId": "1**********************1",
                "RoleName": "企业印章管理员",
                "RoleStatus": 1,
                "SubOrgIdList": []
            },
            {
                "IsGroupRole": false,
                "RoleId": "2*********************0",
                "RoleName": "部门业务管理员",
                "RoleStatus": 1,
                "SubOrgIdList": []
            },
            {
                "IsGroupRole": false,
                "RoleId": "3**************************c",
                "RoleName": "业务员",
                "RoleStatus": 1,
                "SubOrgIdList": []
            },
            {
                "IsGroupRole": false,
                "RoleId": "a******************************9",
                "RoleName": "企业合同管理员",
                "RoleStatus": 1,
                "SubOrgIdList": []
            }
        ],
        "Limit": 5,
        "Offset": 0,
        "RequestId": "s*******************",
        "TotalCount": 13
    }
}

示例3 示例-查询企业角色列表（返回角色对应的权限树）

通过添加过滤参数 IsReturnPermissionGroup 可返回角色对应的权限树信息。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeIntegrationRoles
<公共请求参数>

{
    "Filters": [
        {
            "Key": "IsReturnPermissionGroup",
            "Values": [
                "1"
            ]
        }
    ],
    "Operator": {
        "UserId": "y******************5"
    },
    "Limit": 5,
    "Offset": 0
}

输出示例

{
    "Response": {
        "IntegrateRoles": [
            {
                "IsGroupRole": false,
                "RoleId": "b4******************bf",
                "RoleName": "超级管理员",
                "RoleStatus": 1,
                "SubOrgIdList": [],
                "PermissionGroups": []
            },
            {
                "IsGroupRole": false,
                "RoleId": "1**********************1",
                "RoleName": "企业印章管理员",
                "RoleStatus": 1,
                "SubOrgIdList": [],
                "PermissionGroups": []
            }
        ],
        "Limit": 5,
        "Offset": 0,
        "RequestId": "s*******************",
        "TotalCount": 2
    }
}

5. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。

错误码	描述
FailedOperation	操作失败。
InternalError	内部错误。
InvalidParameter	参数错误。
InvalidParameter.Limit	Limit参数超出最大限制
InvalidParameter.Offset	参数Offset不正确
InvalidParameter.ParamError	参数错误。
MissingParameter	缺少参数错误。
OperationDenied	操作被拒绝。
OperationDenied.Forbid	禁止此项操作。
OperationDenied.SubOrgNotJoin	子企业暂未加入。
UnauthorizedOperation	未授权操作。
UnauthorizedOperation.NoPermissionFeature	请升级到对应版本后即可使用该接口。