关于腾讯 IM REST API
REST API 是腾讯即时通信 IM 提供给服务端的一组 HTTP 后台管理接口，如消息管理、群组管理、用户管理、会话管理等等。REST API 接口较为原始，管理能力强大。另外，为了安全性，REST API 仅提供 HTTPS 接口。
开发前准备
(1）开发前需要申请 SDK 开发者 ID 及密钥，如何获取请参照如下链接：
腾讯IM即时通信控制台
(2）调用 REST API 之前，需要生成 UserSig ，UserSig 是用户登录即时通信 IM 的密码，其本质是对 UserID 等信息加密后得到的密文，如何生成 UserSig 请参照我的文章《C# 生成腾讯云 IM 之 TLSSigAPIv2 UserSig》，通过 TLSSigAPIv2 类进行创建，请参考如下代码：
代码语言：javascript复制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 类，创建及访问示例如下：
代码语言：javascript复制TCAcount tca = new TCAcount();
string SDKAppId=tca.SDKAppId;
string SDKAppIdSecret=tca.SDKAppIdSecret;(4) 用到两个时间戳函数，代码如下:
代码语言：javascript复制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
添加单个账号
AddAccount 方法为 IM 应用系统创建一个内部 ID 帐户，重复添加只生成一个 ID。其关键属性方法说明如下：
序号 | 参数 | 类型 | 说明 |
|---|---|---|---|
1 | From_Account | string | 用户名，长度不超过32字节 |
2 | nickName | string | 用户昵称 |
3 | faceUrl | string | 用户头像 URL |
实现代码如下：
代码语言：javascript复制//导入单个账号
public string AddAccount(string From_Account, string nickName, string faceUrl)
{
ArrayList data = new ArrayList();
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/im_open_login_svc/account_import?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 = "{"Identifier":"" From_Account "","Nick":"" nickName "","FaceUrl":"" faceUrl ""}";
settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
WebService ws = new WebService();
string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
return resultStr;
}添加好友
AddFriend 方法为指定的帐户添加一个好友 ID。其关键属性方法说明如下：
序号 | 参数 | 类型 | 说明 |
|---|---|---|---|
1 | From_Account | string | 需要为该 UserID 添加好友 |
2 | To_Account | string | 好友的 UserID |
实现代码如下：
代码语言：javascript复制//添加好友
public string AddFriend(string From_Account, string To_Account)
{
ArrayList data = new ArrayList();
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/sns/friend_add?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="{ "From_Account":"" From_Account "","AddFriendItem":[ { "To_Account":"" To_Account "", "AddSource":"AddSource_Type_SYSTEM" }],"AddType":"Add_Type_Both","ForceAddFlags":1}";
settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random );
WebService ws = new WebService();
string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
return resultStr;
}删除好友
DeleteFriend 方法为指定的帐户删除一个好友 ID。其关键属性方法说明如下：
序号 | 参数 | 类型 | 说明 |
|---|---|---|---|
1 | From_Account | string | 需要删除该 UserID 的好友 |
2 | To_Account | string | 待删除的好友的 UserID |
实现代码如下：
代码语言：javascript复制//删除好友
public string DeleteFriend(string From_Account, string To_Account)
{
ArrayList data = new ArrayList();
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/sns/friend_delete?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 = "{ "From_Account":"" From_Account "","To_Account":["" To_Account ""],"DeleteType":"Delete_Type_Both"}";
settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
WebService ws = new WebService();
string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
return resultStr;
}拉取好友
GetFriends 方法为指定用户的 UserID 拉取好友数据。其关键属性方法说明如下：
序号 | 参数 | 类型 | 说明 |
|---|---|---|---|
1 | From_Account | string | 需要拉取好友的 UserID |
实现代码如下：
代码语言：javascript复制//拉取好友
public string GetFriends(string From_Account)
{
ArrayList data = new ArrayList();
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/sns/friend_get?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 = "{ "From_Account":"" From_Account "","StartIndex": 0}";
settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
WebService ws = new WebService();
string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
return resultStr;
}删除帐户
DeleteAccounts 方法可删除 IM 应用系统内的一个或多个 UserID 帐户。其关键属性方法说明如下：
序号 | 参数 | 类型 | 说明 |
|---|---|---|---|
1 | Accounts | string | 要删除的 UserID 的列表，多个之间用逗号分隔，如 "user1,user2,user3" |
实现代码如下：
代码语言：javascript复制//删除账号
public string DeleteAccounts(string Accounts)
{
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/im_open_login_svc/account_delete?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[] acs=Accounts.Split(',');
string _acs="";
foreach(string userid in acs){
_acs ="{"UserID":"" userid ""},";
}
if(_acs.Length>0){
_acs=_acs.Substring(0,_acs.Length-1);
}
string content = "{"DeleteItem":[" _acs "]}";
settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
WebService ws = new WebService();
string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
return resultStr;
}查询帐户状态
QueryAccountsState 方法可查询 IM 应用系统内的一个或多个 UserID 帐户的在线状态。其关键属性方法说明如下：
序号 | 参数 | 类型 | 说明 |
|---|---|---|---|
1 | Accounts | string | 要查询的 UserID 的列表，多个之间用逗号分隔，如 "user1,user2,user3" 返回的用户状态，目前支持的状态有： 前台运行状态（Online）：客户端登录后和即时通信 IM 后台有长连接 后台运行状态（PushOnline）：iOS 和 Android 进程被 kill 或因网络问题掉线，进入 PushOnline 状态，此时仍然可以接收消息的离线推送。客户端切到后台，但是进程未被手机操作系统 kill 掉时，此时状态仍是 Online 未登录状态（Offline）：客户端主动退出登录或者客户端自上一次登录起7天之内未登录过 如果用户是多终端登录，则只要有一个终端的状态是 Online ，该字段值就是 Online |
实现代码如下：
代码语言：javascript复制//查询用户状态
public string QueryAccountsState(string Accounts)
{
TCAcount tca = new TCAcount();
//请求地址
string settingUrl = "https://console.tim.qq.com/v4/openim/querystate?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[] acs = Accounts.Split(',');
string _acs = "";
foreach (string userid in acs)
{
_acs = """ userid "",";
}
if (_acs.Length > 0)
{
_acs = _acs.Substring(0, _acs.Length - 1);
}
string content = "{"IsNeedDetail": 1,"To_Account": [" _acs "]}";
settingUrl = string.Format(settingUrl, tca.SDKAppId, AppAdminId, _sig, random);
WebService ws = new WebService();
string resultStr = ws.GetResponseResult(settingUrl, Encoding.UTF8, "POST", content);
return resultStr;
}小结
腾讯云 IM REST API 提供了非常丰富与完善的管理功能列表，在这里我们仅是以满足自身应用需要而提取的常用帐户管理功能，更多详情请参照如下链接：
https://www.tencentcloud.com/zh/document/product/1047/34621
本文代码仅供您参考使用，您可以参照官方文档开发出更加贴合自身需求的应用，感谢您的阅读，希望本文能够对您有所帮助。
