C# 实现腾讯云 IM 常用 REST API 之群组管理

初九之潜龙勿用

发布于 2024-06-20 13:28:50

880

发布于 2024-06-20 13:28:50

文章被收录于专栏：技术文章

----关于腾讯 IM REST API

REST API 是腾讯即时通信 IM 提供给服务端的一组 HTTP 后台管理接口，如消息管理、群组管理、用户管理、会话管理等等。REST API 接口较为原始，管理能力强大。另外，为了安全性，REST API 仅提供 HTTPS 接口，本文将主要介绍常用的群组管理API。

开发前准备

(1）开发前需要申请 SDK 开发者 ID 及密钥，如何获取请参照如下链接：

腾讯IM即时通信控制台

(2）调用 REST API 之前，需要生成 UserSig ，UserSig 是用户登录即时通信 IM 的密码，其本质是对 UserID 等信息加密后得到的密文，如何生成 UserSig 请参照我的文章《C# 生成腾讯云 IM 之 TLSSigAPIv2 UserSig》，通过 TLSSigAPIv2 类进行创建，请参考如下代码：

string SDKAppId="申请的SDKAppID";  
string SDKAppIdSecret="申请的SDKAppIdSecret";  
string AppAdminId="IM平台超级管理员UserID";

TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(SDKAppId),SDKAppIdSecret);
string _sig = sig.GenSig(AppAdminId);

(3）SDKAppID 及 SDKAppIdSecret 的获取在后续范例中均封装为 TCAcount 类，创建及访问示例如下：

TCAcount tca = new TCAcount();
string SDKAppId=tca.SDKAppId;
string SDKAppIdSecret=tca.SDKAppIdSecret;

(4) 用到两个时间戳函数，代码如下:

public string getTimestamp(int seconds)
{
        TimeSpan ts = DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, 0);
        return Convert.ToInt64(ts.TotalSeconds + seconds).ToString();
}
public string GetTimeStamp(DateTime dtime)
{
        TimeSpan tspan = dtime.ToUniversalTime() - new DateTime(1970, 1, 1, 0, 0, 0, 0);
        return Convert.ToInt64(tspan.TotalSeconds).ToString();
}

(5) WebService 类实现访问 REST API URL 地址并 POST 数据，以获取返回结果 Json 的功能。具体实现请参照我的文章《C# 实现访问 Web API Url 提交数据并获取处理结果》

范例运行环境

操作系统： Windows Server 2019 DataCenter

.net版本： .netFramework4.0 或以上

开发工具：VS2019 C#

常用群组管理API

创建群组

CreateGroup 方法为 IM 应用系统创建一个群组。其关键属性方法说明如下：

序号	参数	类型	说明
1	GroupId	string	必填：群组ID
2	Owner_Account	string	群主 ID（已存在的账号）。填写后自动添加到群成员中；如果不填，群没有群主；成员使用 AVChatroom（直播群）时，必须每次调用进群操作
3	Type	string	必填：群组形态，包括 Public（陌生人社交群），Private（即 Work，好友工作群），ChatRoom（即 Meeting，会议群），AVChatRoom（直播群），Community（社群）
4	Name	string	必填：群名称，最长30字节，使用 UTF-8 编码，1个汉字占3个字节
5	Introduction	string	群简介，最长240字节，使用 UTF-8 编码，1个汉字占3个字节
6	Notification	string	群公告，最长300字节，使用 UTF-8 编码，1个汉字占3个字节
7	FaceUrl	string	群头像 URL，最长100字节
8	ApplyJoinOption	string	申请加群处理方式。包含 FreeAccess（自由加入），NeedPermission（需要验证），DisableApply（禁止加群），不填默认为 NeedPermission（需要验证）仅当创建支持申请加群的群组时，该字段有效。社群目前不支持此字段

实现代码如下：

public string CreateGroup(string GroupId,string Owner_Account, string Type, string Name, string Introduction, string Notification, string FaceUrl, string ApplyJoinOption)
                {
                    ArrayList data = new ArrayList();
                    TCAcount tca = new TCAcount();
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/create_group?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
                    string AppAdminId = "administrator";
                    Random rnd = new Random();
                    string random = rnd.Next(0, 429496729).ToString();
                    TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
                    string _sig = sig.GenSig(AppAdminId);
                    string content = "{\"Owner_Account\": \""+Owner_Account+"\", \"Type\": \""+Type+"\", \"GroupId\": \""+GroupId+"\",\"Name\": \""+Name+"\",\"Introduction\":\""+Introduction+"\"," +
                                     "\"Notification\": \""+Notification+"\",\"FaceUrl\": \""+FaceUrl+"\",\"ApplyJoinOption\": \""+ApplyJoinOption+"\"}";

                    settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                    WebService ws = new WebService();

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
                }

增加群成员

AddGroupUser 方法向指定的群中添加新成员用户。其关键属性方法说明如下：

序号	参数	类型	说明
1	GroupId	string	要添加新成员的群组 ID
2	Account	string	要添加的群成员 UserID
3	Silence	string	是否静默加人。0：非静默加人；1：静默加人。不填该字段默认为0

实现代码如下：

//增加群成员
public string AddGroupUser(string GroupId, string Account, string Silence)
{
                    TCAcount tca = new TCAcount();
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/add_group_member?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
                    string AppAdminId = "administrator";
                    Random rnd = new Random();
                    string random = rnd.Next(0, 429496729).ToString();
                    TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
                    string _sig = sig.GenSig(AppAdminId);
                    string content = "{\"GroupId\": \""+GroupId+"\",\"Silence\": "+Silence+",\"MemberList\": [ {\"Member_Account\": \""+Account+"\"}]}";

                    settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                    WebService ws = new WebService();

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
}

修改群基础资料

ModifyGroupBaseInfo 方法可修改指定群组的基础信息。其关键属性方法说明如下：

序号	参数	类型	说明
1	GroupId	string	要修改的群组 ID
2	Name	string	群名称，最长30字节，使用 UTF-8 编码，1个汉字占3个字节
3	Introduction	string	群简介，最长240字节，使用 UTF-8 编码，1个汉字占3个字节
4	FaceUrl	string	群头像 URL，最长100字节
5	ApplyJoinOption	string	申请加群处理方式。包含 FreeAccess（自由加入），NeedPermission（需要验证），DisableApply（禁止加群），不填默认为 NeedPermission（需要验证）仅当创建支持申请加群的群组时，该字段有效。社群目前不支持此字段
6	ShutUpAllMember	string	群内群成员禁言，只有群管理员和群主以及系统管理员可以发言，"On"开启，"Off"关闭

实现代码如下：

//修改群基础资料
public string ModifyGroupBaseInfo(string GroupId, string Name, string Introduction, string FaceUrl, string ApplyJoinOption, string ShutUpAllMember)
{
                    TCAcount tca = new TCAcount();
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/modify_group_base_info?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
                    string AppAdminId = "administrator";
                    Random rnd = new Random();
                    string random = rnd.Next(0, 429496729).ToString();
                    TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
                    string _sig = sig.GenSig(AppAdminId);
                    string name = Name == "" ? "" : ", \"Name\":\"" + Name + "\"";
                    string intro = Introduction == "" ? "" : ", \"Introduction\":\"" + Introduction + "\"";
                    string faceurl = FaceUrl == "" ? "" : ", \"FaceUrl\":\"" + FaceUrl + "\"";
                    string joinoption = ApplyJoinOption == "" ? "" : ", \"ApplyJoinOption\":\"" + ApplyJoinOption + "\"";

                    string content = "{\"GroupId\":\""+GroupId+"\""+name+intro+faceurl+joinoption+"}";

                    settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                    WebService ws = new WebService();

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
} //edit_group_info

修改群成员资料

ModifyGroupUser 方法可以修改指定群成员用户的资料。其关键属性方法说明如下：

序号	参数	类型	说明
1	GroupId	string	要修改操作的群组 ID
2	Account	string	要操作的群成员UserID
3	Role	string	成员身份，Admin/Member 分别为设置/取消管理员（不允许修改群主的身份）
4	MsgFlag	string	设置的指定成员消息屏蔽类型： AcceptAndNotify 代表接收并提示消息，Discard 代表不接收也不提示消息，AcceptNotNotify 代表接收消息但不提示。
5	NameCard	string	指定成员的群名片，最大不超过50个字节。
6	ShutUpTime	int	指定群成员的禁言时间，单位为秒。

实现代码如下：

public string ModifyGroupUser(string GroupId, string Account, string Role,string MsgFlag,string NameCard,int ShutUpTime)
{
                    TCAcount tca = new TCAcount();
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/modify_group_member_info?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
                    string AppAdminId = "administrator";
                    Random rnd = new Random();
                    string random = rnd.Next(0, 429496729).ToString();
                    TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
                    string _sig = sig.GenSig(AppAdminId);
                    string role = Role == "" ? "" : ", \"Role\":\""+Role+"\"";
                    string msgflag = MsgFlag == "" ? "" : ", \"MsgFlag\":\"" + MsgFlag + "\"";
                    string namecard = NameCard == "" ? "" : ", \"NameCard\":\"" + NameCard + "\"";
                    string shutuptime = ShutUpTime == -1 ? "" : ", \"ShutUpTime\":" + ShutUpTime + "";

                    string content = "{\"GroupId\":\""+GroupId+"\", \"Member_Account\":\""+Account+"\""+role+msgflag+namecard+shutuptime+"}";

                    settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                    WebService ws = new WebService();

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
}

获取被禁言群成员列表

GetGroupShuttedList 方法可获取根据群组 ID 获取群组中被禁言的用户列表。其关键属性方法说明如下：

序号	参数	类型	说明
1	GroupId	string	要获取操作的群组 ID

实现代码如下：

public string GetGroupShuttedList(string GroupId)
{
                    TCAcount tca = new TCAcount();
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/get_group_shutted_uin?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
                    string AppAdminId = "administrator";
                    Random rnd = new Random();
                    string random = rnd.Next(0, 429496729).ToString();
                    TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
                    string _sig = sig.GenSig(AppAdminId);

                    string content = "{\"GroupId\":\"" + GroupId + "\"}";

                    settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                    WebService ws = new WebService();

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
}

解散群组

DestoryGroup 方法可解散指定ID的群组。其关键属性方法说明如下：

序号	参数	类型	说明
1	GroupId	string	要解散的群组ID

实现代码如下：

public string DestoryGroup(string GroupId)
{
                    ArrayList data = new ArrayList();
                    TCAcount tca = new TCAcount();
                    //请求地址
                    string settingUrl = "https://console.tim.qq.com/v4/group_open_http_svc/destroy_group?sdkappid={0}&identifier={1}&usersig={2}&random={3}&contenttype=json";
                    string AppAdminId = "administrator";
                    Random rnd = new Random();
                    string random = rnd.Next(0, 429496729).ToString();
                    TLSSigAPIv2 sig = new TLSSigAPIv2(int.Parse(tca.SDKAppId), tca.SDKAppIdSecret);
                    string _sig = sig.GenSig(AppAdminId);
                    string content = "{\"GroupId\": \"" + GroupId + "\"}";

                    settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
                    WebService ws = new WebService();

                    string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
                    return resultStr;
}