查询用户组列表

最近更新时间: 2026-10-12 00:11:06

1. 接口描述

接口请求域名： cic.api3.fincloud.tencent.com。

查询用户组列表

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

接口更新时间：2024-12-11 12:17:58。

接口既验签名又鉴权。

2. 输入参数

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

参数名称 必选 允许NULL 类型 描述
Action 是 否 String 公共参数，本接口取值：ListGroups
Version 是 否 String 公共参数，本接口取值：2021-03-31
Region 是 否 String 公共参数，地域信息本接口不需要传递此参数。
NextToken 否 是 String 查询返回结果下一页的令牌。首次调用 API 不需要NextToken。  当您首次调用 API 时，如果返回数据总条数超过MaxResults限制，数据会被截断，只返回MaxResults条数据，同时，返回参数IsTruncated为true，返回一个NextToken。您可以使用上一次返回的NextToken继续调用 API，其他请求参数保持不变，查询被截断的数据。您可以按此方法多次查询，直到IsTruncated为false，表示全部数据查询完毕。
示例值： sjdhdhw
Filter 否 是 String 过滤条件。  格式：  ，不区分大小写。目前，只支持GroupName，只支持eq（Equals）和sw（Start With）。  示例：Filter = "GroupName sw test"，表示查询名称以 test 开头的全部用户组。Filter = "GroupName eq testgroup"，表示查询名称为 testgroup 的用户组。
示例值： user1
GroupType 否 是 String 用户组的类型  Manual：手动创建，Synchronized：外部导入。
示例值： Manual
ZoneId 是 是 String 空间 ID。
示例值： z-2d8shd8***
FilterUsers 否 是 Array of String 筛选的用户，该用户关联的用户组会返回IsSelected=1
示例值： user1
SortField 否 是 String 排序的字段，目前只支持CreateTime，默认是CreateTime字段
示例值： CreateTime
SortType 否 是 String 排序类型：Desc 倒序 Asc  正序，需要您和SortField一起设置
示例值： Desc
Offset 否 是 Int64 翻页offset. 不要与NextToken同时使用，优先使用NextToken
示例值： 0
MaxResults 否 是 Int64 每页的最大数据条数。  取值范围：1~100。  默认值：10。
示例值： 1

3. 输出参数

参数名称 类型 描述
MaxResults Int64 每页的最大数据条数。
示例值： 1
TotalCounts Int64 符合请求参数条件的数据总条数。
示例值： 1
IsTruncated Bool 返回结果是否被截断。取值：  true：已截断。 false：未截断。
示例值： true
NextToken String 查询返回结果下一页的令牌。  说明 只有IsTruncated为true时，才显示该参数。
示例值： sjdhdhw
Groups Array of GroupInfo 用户组列表。
示例值：查看
RequestId String 唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 错误码

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

错误码 描述
InvalidParameter.ParamError
FailedOperation.IdentityCenterNotOpen
FailedOperation.ZoneIdNotExist
InvalidParameter.NextTokenInvalid

5. 示例

示例1 查询用户组列表

输入示例

{
  "ZoneId": "z-32s7dhd8s***",
  "MaxResults": 20,
  "GroupType": "Manual"
}

输出示例

{
  "Response": {
    "NextToken": "OTM0YzE4MzY2ZjdhMWM0MYZD******",
    "Groups": [
      {
        "GroupName": "testGroup",
        "Description": "thsi is group",
        "CreateTime": "2024-01-01 12:12:12",
        "GroupType": "Manual",
        "UpdateTime": "2024-01-01 12:12:12",
        "GroupId": "g-q8shs8h****",
        "MemberCount": 20
      }
    ],
    "MaxResults": 10,
    "TotalCounts": 30,
    "IsTruncated": true,
    "RequestId": "e297543a-80de-4039-83c8-9d35d4545"
  }
}