获取权限组成员列表
功能说明
App 管理员可以根据群组 ID 获取群组成员的资料。
接口调用说明
适用的群组类型
群组类型 ID | 是否支持此 REST API |
Private | 不支持,同新版本中的 Work(好友工作群) |
Public | 不支持 |
ChatRoom | 不支持,同新版本中的 Meeting(临时会议群) |
AVChatRoom | 不支持 |
Community(社群) | 支持 |
请求 URL 示例
https://xxxxxx/v4/group_open_http_svc/get_permission_group_member_list?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
请求参数说明
参数 | 说明 |
xxxxxx | SDKAppID 所在国家/地区对应的专属域名: 中国: console.tim.qq.com 新加坡: adminapisgp.im.qcloud.com 首尔: adminapikr.im.qcloud.com 法兰克福: adminapiger.im.qcloud.com 硅谷: adminapiusa.im.qcloud.com 雅加达: adminapiidn.im.qcloud.com |
v4/group_open_http_svc/get_permission_group_member_list | 请求接口 |
sdkappid | 创建应用时即时通信 IM 控制台分配的 SDKAppID |
identifier | |
usersig | |
random | 请输入随机的32位无符号整数,取值范围0 - 4294967295 |
contenttype | 请求格式固定值为 json |
最高调用频率
200次/秒。
请求包示例
基础形式
用来获取权限组成员详细信息(群成员资料和群成员维度自定义字段),请求中只包含群 ID和权限组 ID。
{"GroupId": "@TGS#_@TGS#cAVQXXXXXX", // 群组 ID(必填)"PermissionGroupId":"@PMG#_@PMG#cDR",// 权限组 ID(必填)}
分批获取
使用 Limit 和 Next 两个值用于控制分页拉取:
Limit 限制回包中 MemberList 数组中成员的个数,不得超过50。
Next 控制从某一个成员位置拉取后续的信息。第一次请求时,客户端请求参数 Next 传"";最后一次请求服务端返回的 Next 为""时,代表拉取结束;
中间的请求,客户端的 Next 均使用上一次服务端返回的 Next。类似 redis 的 scan 游标查询。
例如:假设需要分批拉取,第一次的请求参数应当为:
{"Limit" : 20, "Next" : ""}
,服务端返回 。{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1","MemberList": [....
第二次请求参数应当为
{"Limit" : 20, "Next" : "
TGSMTQ0MTE1MjM1MTUyNDI0MzY1"}
。
以此类推,直到服务端的应答包返回 Next 为"",代表无后续成员信息,客户端应结束查询。{"GroupId":"@TGS#_@TGS#cAVQXXXXXX", // 群组 ID(必填)"PermissionGroupId":"@PMG#_@PMG#cDR",// 权限组 ID(必填)"Limit": 50, // 最多获取多少个成员的资料"Next": "" // 从上次拉取结束的位置开始拉取}
指定拉取的信息
通过 MemberInfoFilter 过滤器字段选择需要拉取的字段。没有在过滤器中指明的字段将不被拉取。
{"GroupId":"@TGS#_@TGS#cAVQXXXXXX", // 群组 ID(必填)"PermissionGroupId":"@PMG#_@PMG#cDR",// 权限组 ID(必填)"MemberInfoFilter": [ // 需要获取哪些信息(Member_Account 被默认包含在其中),如果没有该字段则为群成员全部资料"Role","JoinTime","MsgSeq","MsgFlag","LastSendMsgTime","JoinPermissionGroupTime","MuteUntil","NameCard"]}
拉取群成员自定义字段
通过 AppDefinedDataFilter_GroupMember 过滤器选取需要拉取的成员自定义字段。没有在过滤器中指明的字段将不被拉取。
{"GroupId":"@TGS#_@TGS#cAVQXXXXXX", // 群组 ID(必填)"PermissionGroupId":"@PMG#_@PMG#cDR",// 权限组 ID(必填)"AppDefinedDataFilter_GroupMember": [ // 群成员自定义字段过滤器"MemberDefined2" // 群成员自定义字段Key]}
ALL IN ONE
{"GroupId":"@TGS#_@TGS#cAVQXXXXXX", // 群组 ID(必填)"PermissionGroupId":"@PMG#_@PMG#cDR",// 权限组 ID(必填)"MemberInfoFilter": [ // 需要获取哪些信息,如果没有该字段则为群成员全部资料"Role","JoinTime","JoinPermissionGroupTime","MsgSeq","MsgFlag","LastSendMsgTime","MuteUntil","NameCard"],"AppDefinedDataFilter_GroupMember": [ // 群成员自定义字段过滤器"MemberDefined2", // 群成员自定义字段 Key"MemberDefined1"],"Limit": 50, // 最多获取多少个成员的资料"Offset": 0 // 从第多少个成员开始获取}
请求包字段说明
字段 | 类型 | 属性 | 说明 |
GroupId | String | 必填 | 需要拉取成员信息的群组的 ID |
PermissionGroupId | String | 必填 | 操作的权限组 ID |
MemberInfoFilter | Array | 选填 | |
AppDefinedDataFilter_GroupMember | Array | 选填 | |
Next | String | 选填 | 上一次拉取到的成员位置,社群必填,社群不支持 Offset 参数,使用 Next 参数,首次调用填写"",续拉使用返回中的 Next 值 |
应答包体示例
基本形式和分页拉取
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1","MemberNum": 2, // 本权限组的成员总数"MemberList": [ // 权限组成员列表{"Member_Account": "bob","Role": "Owner","JoinTime": 1425976500, // 入群时间"JoinPermissionGroupTime": 1704804868, // 加入权限组时间"MsgSeq": 1233,"MsgFlag": "AcceptAndNotify","LastSendMsgTime": 1425976500, // 最后一次发消息的时间"MuteUntil": 1431069882, // 禁言截至时间(秒数)"AppMemberDefinedData": [ //群成员自定义字段{"Key": "MemberDefined1","Value": "ModifyDefined1"},{"Key": "MemberDefined2","Value": "ModifyDefined2"}]},{"Member_Account": "peter","Role": "Member ","JoinTime": 1425976500, // 入群时间"JoinPermissionGroupTime": 1704804868, // 加入权限组时间"MsgSeq": 1233,"MsgFlag": "AcceptAndNotify","LastSendMsgTime": 1425976500,"MuteUntil": 0, // 0表示未被禁言,否则为禁言的截止时间戳"AppMemberDefinedData": [ // 群成员自定义字段{"Key": "MemberDefined1","Value": "ModifyDefined1"},{"Key": "MemberDefined2","Value": "ModifyDefined2"}]}]}
拉取指定字段
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1","MemberNum": 2, // 本权限组的成员总数"MemberList": [ // 权限组成员列表{"Member_Account": "bob","Role": "Owner","JoinTime": 1425976500, // 入群时间"JoinPermissionGroupTime": 1704804868, // 加入权限组时间"MsgSeq": 1233,"MsgFlag": "AcceptAndNotify","LastSendMsgTime": 1425976500, // 最后一次发消息的时间"MuteUntil": 1431069882, // 禁言截至时间(秒数)},{"Member_Account": "peter","Role": "Member ","JoinTime": 1425976500, // 入群时间"JoinPermissionGroupTime": 1704804868, // 加入权限组时间"MsgSeq": 1233,"MsgFlag": "AcceptAndNotify","LastSendMsgTime": 1425976500,"MuteUntil": 0, // 0表示未被禁言,否则为禁言的截止时间戳}]}
拉取群成员自定义字段
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1","MemberNum": 2, // 本权限组的成员总数"MemberList": [ // 权限组成员列表{"Member_Account": "bob","Role": "Owner","JoinTime": 1425976500, // 入群时间"JoinPermissionGroupTime": 1704804868, // 加入权限组时间"MsgSeq": 1233,"MsgFlag": "AcceptAndNotify","LastSendMsgTime": 1425976500, // 最后一次发消息的时间"MuteUntil": 1431069882, // 禁言截至时间(秒数)"AppMemberDefinedData": [ // 群成员自定义字段{"Key": "MemberDefined2","Value": "ModifyDefined2"}]},{"Member_Account": "peter","Role": "Member","JoinTime": 1425976500, // 入群时间"JoinPermissionGroupTime": 1704804868, // 加入权限组时间"MsgSeq": 1233,"MsgFlag": "AcceptAndNotify","LastSendMsgTime": 1425976500,"MuteUntil": 0, // 0表示未被禁言,否则为禁言的截止时间戳"AppMemberDefinedData": [ // 群成员自定义字段{"Key": "MemberDefined2","Value": "ModifyDefined2"}]}]}
ALL IN ONE
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0,"Next": "TGSMTQ0MTE1MjM1MTUyNDI0MzY1","MemberNum": 2, // 本权限组的成员总数"MemberList": [ // 权限组成员列表{"Member_Account": "bob","Role": "Owner","JoinTime": 1425976500, // 入群时间"JoinPermissionGroupTime": 1704804868, // 加入权限组时间"MsgSeq": 1233,"MsgFlag": "AcceptAndNotify","LastSendMsgTime": 1425976500, // 最后一次发消息的时间"MuteUntil": 1431069882, // 禁言截至时间(秒数)"AppMemberDefinedData":[ // 群成员自定义字段{"Key":"MemberDefined1","Value":"ModifyDefined1"},{"Key":"MemberDefined2","Value":"ModifyDefined2"}]},{"Member_Account": "peter","Role": "Member","JoinTime": 1425976500, // 入群时间"JoinPermissionGroupTime": 1704804868, // 加入权限组时间"MsgSeq": 1233,"MsgFlag": "AcceptAndNotify","LastSendMsgTime": 1425976500,"MuteUntil": 0, // 0表示未被禁言,否则为禁言的截止时间戳"AppMemberDefinedData": [ // 群成员自定义字段{"Key": "MemberDefined1","Value": "ModifyDefined1"},{"Key": "MemberDefined2","Value": "ModifyDefined2"}]}]}
应答包字段说明
字段 | 类型 | 说明 |
ActionStatus | String | 请求处理的结果: OK 表示处理成功 FAIL 表示失败 |
ErrorCode | Integer | 错误码: 0表示成功 非0表示失败 |
ErrorInfo | String | 错误信息 |
MemberNum | Integer | 本权限组的成员总数 |
MemberList | Array | |
AppMemberDefinedData | Array | 返回的群成员自定义字段信息 |
Next | String | 下一次请求应该传的 Next 值 |
错误码说明
除非发生网络错误(例如502错误),否则该接口的 HTTP 返回码均为200。真正的错误码,错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码(60000到79999)参见 错误码 文档。
本 API 私有错误码如下:
错误码 | 描述 |
10002 | 服务器内部错误,请重试 |
10003 | 请求命令字非法 |
10004 | 参数非法,请根据错误描述检查请求是否正确 |
10007 | 操作权限不足,请确认操作者是否是 App 管理员或者是否有权限读取请求中的字段 |
10010 | 群组不存在,或者曾经存在过,但是目前已经被解散 |
10015 | 群组 ID 非法,请检查群组 ID 是否填写正确 |
110006 | 权限组不存在,或者曾经存在过,但是目前已经被解散 |
110008 | 权限组 ID 非法,请检查权限组 ID 是否填写正确 |