【新手必看】服务端集成网易云信IM 即时通讯-阿里云开发者社区

【新手必看】服务端集成网易云信IM 即时通讯

2024-07-12 56

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

本文涉及的产品

.cn 域名，1个 12个月

简介： 【新手必看】服务端集成网易云信IM 即时通讯

了解网易云信 IM

网易云信 IM 即时通讯服务基于网易二十余年的 IM 技术积累，致力于打造最稳定的即时通讯云平台。

IM 即时通讯服务提供了一整套即时通讯基础能力。通过该平台服务就可以将即时通讯、实时网络能力快速集成至企业自身应用中。针对不同场景，网易提供了一系列产品、技术解决方案，包括：客户端 IM 组件、客户端 IM 基础库、全平台 SDK 以及服务端 API 等。利用这些解决方案，企业可以直接在自身的应用中搭建出即时通讯产品，也可以无限创意出自己的即时通讯场景。

通过网易云信 IM SDK，不仅可以快速实现私信、即时聊天、消息通知、游戏对战通讯等常见功能，还能完整打造类似 Discord、微信、子弹短信、易信等的大用户量级社交产品。

集成概述

服务端集成与客户端集成相辅相成，前者实现您的应用服务端与云信 IM 服务端的数据交互，后者实现您的应用客户端与云信 IM 服务端的数据交互。

更新圈组后的IM架构图.png

应用服务端和云信 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'

HttpClient 请求示例（Java）

import 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”。