服务端集成新手必看
更新时间： 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”。
