服务端集成新手必看
更新时间: 2024/07/17 17:57:35
本文为新手介绍如何快速了解网易云信即时通讯 IM(Instant Messaging)服务、IM 服务端集成原理,服务端 API 使用流程、以及状态码的查询路径。
了解网易云信 IM
网易云信 IM 即时通讯服务基于网易二十余年的 IM 技术积累,致力于打造最稳定的即时通讯云平台。
IM 即时通讯服务提供了一整套即时通讯基础能力。通过该平台服务就可以将即时通讯、实时网络能力快速集成至企业自身应用中。针对不同场景,网易提供了一系列产品、技术解决方案,包括:客户端 IM 组件、客户端 IM 基础库、全平台 SDK 以及服务端 API 等。利用这些解决方案,企业可以直接在自身的应用中搭建出即时通讯产品,也可以无限创意出自己的即时通讯场景。
通过网易云信 IM SDK,不仅可以快速实现私信、即时聊天、消息通知、游戏对战通讯等常见功能,还能完整打造类似 Discord、微信、子弹短信、易信等的大用户量级社交产品。
集成概述
服务端集成与客户端集成相辅相成,前者实现您的应用服务端与云信 IM 服务端的数据交互,后者实现您的应用客户端与云信 IM 服务端的数据交互。
应用服务端和云信 IM 服务端的数据交互按数据流通方向可分为下表所示的两种类型。
服务端集成类型 |
相关文档 |
---|---|
应用服务端请求云信 IM 服务端 | API调用方式 |
云信 IM 服务端请求应用服务端 |
大部分服务端 API 能够实现和 SDK 接口相同的效果,但部分能力仅可通过服务端 API 实现,如注册云信 IM 账号和创建聊天室。
服务端 API 使用流程
应用服务端请求云信 IM 服务端的操作流程如下。IM 服务端请求应用服务端的相关说明,请参见 第三方回调、 消息抄送和 安全通。
本文以注册云信 IM 账号(user/create.action
)这个 API 为例,详细介绍服务端 API 的使用流程。
前提条件
- 已在云信控制台创建应用,获取 App Key。
- 已准备好调用和调试服务端 API 的开发环境,如 cURL 和 Postman。
步骤1:确认请求地址(URL)
云信 IM 服务端根据不同的请求地址(URL),区分不同的请求。 因此,您需先到服务端 《API 参考》的相应 API 文档的请求说明中,获取请求地址。
以下为注册云信 IM 账号(user/create.action
)的请求地址:
https://api.netease.im/nimserver/user/create.action
该请求地址可分为如下几个部分:
-
https
:指定请求的通信协议。 -
api.netease.im/nimserver
:指定云信 IM 服务端的接入地址。 -
user/create.action
:指定调用的 API。上述请求地址的域名(
api.netease.im
)属于国内数据中心域名。如果您的应用主要服务于海外用户,需要将域名设置为海外数据中心域名(api-sg.netease.im
),相应的海外接入地址为https://api-sg.netease.im/nimserver
。更多海外数据中心接入相关说明,请参见接入海外数据中心。
步骤2:生成 CheckSum
为保证 API 的安全调用,云信 IM 服务端会对每个 API 的访问请求进行身份验证。您在调用 API 时,都需要在请求中包含 CheckSum 信息。
CheckSum 可通过将本文前提条件获取的 App Secret 结合 Nonce 和 CurTime 这两个参数拼接成字符串后再进行 SHA1 哈希计算来生成,详情请参见 CheckSum计算示例。
步骤3:配置公共请求参数
调用云信 IM 服务端 API 前,需先配置 API 的公共请求参数,即每个 API 都需要使用的请求参数,包括 App Key、Nonce、CurTime 和 CheckSum。公共请求参数需放在请求头(Request Header)中。
参数 |
说明 |
---|---|
App Key | 通过云信控制台获取,详见获取 App key |
Nonce | 随机数(最大长度128个字符) |
CurTime | 当前 UTC 时间戳,从 1970 年 1 月 1 日 0 时 0 分 0 秒开始到 现在(指发起请求瞬间的前后 5 分钟内)的秒数(类型为 String) |
CheckSum | 即步骤2:生成 CheckSum中的 CheckSum |
步骤4:配置业务参数
配置完公共请求参数后,您需再配置 API 相关的业务参数,明确目标操作。
业务参数的具体介绍,请参见请求参数。
请求参数无论为何类型,调用 API 实际传入时,都需要转为 String 格式,否则将报错。
步骤5:应用服务端发起请求
发起请求
完成以上配置后,您的应用服务端可以通过请求地址,向云信 IM 服务端发起请求。
curl curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw080*****" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan&name=zhangsan' 'https://api.netease.im/nimserver/user/create.action'
javaimport org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
public class Test {
public static void main(String[] args) throws Exception{
DefaultHttpClient httpClient = new DefaultHttpClient();
String url = "https://api.netease.im/nimserver/user/create.action";
HttpPost httpPost = new HttpPost(url);
String appKey = "94kid09c9ig9k1loimjg01******";
String appSecret = "1234567*****";
String nonce = "12345";
String curTime = String.valueOf((new Date()).getTime() / 1000L);
String checkSum = CheckSumBuilder.getCheckSum(appSecret, nonce ,curTime);//参考 计算CheckSum的java代码
// 设置请求的header
httpPost.addHeader("AppKey", appKey);
httpPost.addHeader("Nonce", nonce);
httpPost.addHeader("CurTime", curTime);
httpPost.addHeader("CheckSum", checkSum);
httpPost.addHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
// 设置请求的参数
List<NameValuePair> nvps = new ArrayList<NameValuePair>();
nvps.add(new BasicNameValuePair("accid", "helloworld"));
httpPost.setEntity(new UrlEncodedFormEntity(nvps, "utf-8"));
// 执行请求
HttpResponse response = httpClient.execute(httpPost);
// 打印执行结果
System.out.println(EntityUtils.toString(response.getEntity(), "utf-8"));
}
}
响应请求
云信 IM 服务端接收到您的请求信息后,返回响应信息。
返回示例如下:
"Content-Type": "application/json; charset=utf-8"
{
"code":200,
"info":{"token":"*****","accid":"*****","name":"*****"}
}
状态码
调用 API 发起请求后,云信 IM 服务端会通过状态码告知您 API 调用结果,如上文返回示例中表示调用成功的"code":200
。
如调用不成功,您可根据状态码进行问题排查。具体请参见状态码。
状态码的含义均为开放式,不同接口返回的相同状态码,含义可能略有不同。因此不建议您针对状态码开发业务逻辑。如果对状态码存在依赖,可能存在风险。
常见问题
为什么按照 Boolean 格式传入参数,最终调用 API 失败?
云信 IM 服务端 API 在调用时,请求参数无论为何类型,实际传入时都需转为 String 格式,否则将报错。
以账号全局禁言接口(nimserver/user/mute.action
)为例,虽然请求参数 mute 为 Boolean 类型,但在调用接口时,请不要传入"mute":true,而应该传入"mute":"true",否则将返回错误提示:“mute not boolean”。