Java Server SDK 1.0

大约 10 分钟

Java Server SDK 1.0

功能概述

Server SDK 是对环信 IM REST API 的封装，这样做是为了节省服务器端开发者对接环信 API 的时间，只需要配置自己的 App Key 相关信息即可使用。

Server SDK 提供了用户、消息、群组、聊天室等资源的操作管理能力。

前提条件

实现方法

安装

如果你的项目使用 Maven 构建，在 pom.xml 中添加下面代码：

<dependency>
    <groupId>com.easemob.im</groupId>
    <artifactId>im-sdk-core</artifactId>
    <version>0.8.56</version>
</dependency>

如果你的项目使用 Gradle 构建，可以在 build.gradle 中添加下面代码：

implementation 'com.easemob.im:im-sdk-core:0.8.56'

使用

EMServiceopen in new window 是所有 API 的入口，可以这样初始化：

1. 使用 Easemob App Credentials 的情况

建议写到配置类中，示例如下：
@Configuration
public class Config {

    @Bean
    public EMService service() {

        EMProperties properties = EMProperties.builder()
                .setAppkey("Appkey")
                .setClientId("Client ID")
                .setClientSecret("ClientSecret")
                .build();

        return new EMService(properties);
    }
}

根据业务资源，API 分为：

每个业务资源对应一个方法，例如，用户相关的 API，都可以在 .user() 找到。

举个例子，我们要注册一个用户，就可以这样写：

@Service
public class UserService {

    @Autowired
    private EMService service;

    private void createUser() {
        try {
            EMUser user = service.user().create("username", "password").block();
        } catch (EMException e) {
            e.getErrorCode();
            e.getMessage();
        }

    }
}

API 的返回值是响应式的，如果希望阻塞，可以使用上面例子中的 .block()。

提示

如果你的项目不是响应式的编程，那么请在调用的 Server SDK API 的结尾添加 .block() 对使用的 API 添加 try/catch ，如果使用的 API 没有抛出异常，代表请求成功，反之则请求失败，通过异常 EMException 对象的 getErrorCode()/getMessage() 拿到错误码以及错误描述。

2.私有化配置，将你自己的私有化 REST 服务器地址设置给 setBaseUri 即可。

建议写到配置类中，示例如下：

@Configuration
public class Config {

    @Bean
    public EMService service() {

        EMProperties properties = EMProperties.builder()
                 .setBaseUri("https://Your privatized address name")
                .setAppkey("Appkey")
                .setClientId("Client ID")
                .setClientSecret("ClientSecret")
                .build();

        return new EMService(properties);
    }
}

参考

常见问题

集成问题

如果你想看 Server SDK 的请求与响应，可以在配置文件中添加:

logging.level.com.easemob.im.http=debug

如果在 Mac 系统上使用 Server SDK 出现 Dns 的警告，可以在配置文件中添加:

logging.level.com.easemob.im.shaded.io.netty=error

使用问题

目前有开发者在使用 Server SDK 有遇到 Connection reset by peer 异常的情况，由于 Server SDK 使用的 Netty 来发送请求，该异常是由 Netty 抛出来的，Netty 官方有相关问题的 issue 并有一些解决方案open in new window，不过要依赖于对 Netty 的 ConnectionProvider 进行配置，因此 Server SDK 在 EMProperties 中增加与之对应的配置项，来让开发者针对自己的使用场景进行对 Netty 的 ConnectionProvider 进行配置。比如设置连接数量、连接空闲时间等，如果使用 Server SDK 请求量较大，那可以把连接数设置大一些。

示例：

@Configuration
public class Config {

    @Bean
    public EMService service() {

        EMProperties properties = EMProperties.builder()
                    .setBaseUri("https://Your privatized address name")
                    .setAppkey("Appkey")
                    .setClientId("Client ID")
                    .setClientSecret("Client Secret")
                    .setHttpConnectionPoolSize(500)
                    .setHttpConnectionMaxIdleTime(20000)
                    .setHttpConnectionMaxLifeTime(60000)
                    .setHttpConnectionPendingAcquireTimeout(60000)
                    .setHttpConnectionEvictInBackground(120000)
                    .setServerTimezone("+8")
                    .build();

        return new EMService(properties);
    }
}

注意事项

  1. Server SDK 是对环信 IM REST API 的封装，但并没有封装所有的 API，只封装了开发者常用的 API，点击 这里 查看 Server SDK API。

对于注册环信 ID 的规则，Server SDK 有自己的限制，正则为 ^[a-z][0-9a-z-]{1,32}$，这点与 官网 REST API 文档 中说明的环信 ID 规则是有区别的，例如用户 ID 长度限制为 32 字节以内，这样做是因为目前环信 ID 注册的限制范围比较广，Server SDK 考虑缩小环信 ID 注册的限制范围使其更加规范。

如果不想使用 Server SDK 注册环信 ID 的限制，可以在初始化配置时添加 ‘turnOffUserNameValidation()’ （SDK 需要使用 0.3.5 以上的版本）

// 强烈建议不要使用纯数字或者有规律的字符串来注册环信 ID，否则用户可能容易遭受到攻击、接收到垃圾消息。
EMProperties properties = EMProperties.builder()
        .setAppkey("appkey")
        .setClientId("Client ID")
        .setClientSecret("ClientSecret")
        .turnOffUserNameValidation()
        .build();
  1. 使用代理的情况

前提需要你的代理支持 CONNECT 方法，确保你的代理配置文件中有 connectport 80 存在。

如果你使用的代代理不需要认证，那么需要传入自己的 IP、端口。

EMProxy proxy = EMProxy.builder()
                .setIP("ip")
                .setPort(80)
                .build();

EMProperties properties = EMProperties.builder()
        .setProxy(proxy)
        .setAppkey("appkey")
        .setClientId("Client ID")
        .setClientSecret("ClientSecret")
        .build();

如果你使用的代理需要认证，那么需要传入自己的 IP、端口、账号以及密码。

EMProxy proxy = EMProxy.builder()
                .setIP("ip")
                .setPort(80)
                .setUsername("username")
                .setPassword("password")
                .build();

EMProperties properties = EMProperties.builder()
        .setProxy(proxy)
        .setAppkey("appkey")
        .setClientId("Client ID")
        .setClientSecret("ClientSecret")
        .build();

更新日志

V0.8.56 2024-11-20

  1. 创建用户修改密码长度限制。

以上更新内容请到 UserApi 中查看。

V0.8.55 2024-09-09

  1. 增加 Presence 功能。
  2. 更新 javadoc sdk 文档。

以上更新内容请到 PresenceApi 中查看。

V0.8.54 2024-07-29

  1. 创建群组增加群组头像属性。
  2. 修改群组信息支持群组头像修改。
  3. 获取群组详情增加群组头像属性。
  4. 获取用户已加入的群组列表中增加群组头像属性。

以上更新内容请到 GroupApi 中查看。

V0.8.53 2024-06-28

  1. 增加 "批量设置离线推送时显示的昵称" 功能。

以上更新内容请到 PushApi 中查看。

V0.8.52 2024-06-07

增加 "创建用户带推送昵称" 功能。

以上更新内容请到 UserApi 中查看。

V0.8.51 2024-04-08

  • 增加 "单向清空漫游消息" 功能。
  • 增加 "修改文本或自定义消息" 功能。
  • 增加 "设置好友备注和分页获取好友列表" 功能。

以上更新内容请到 MessageApi 、ContactApi 中查看。

V0.8.2 2024-01-11

  • 增加发送聊天室全局广播功能。
  • 增加群组封禁&群组解禁的功能。

以上更新内容请到 GroupApi & MessageApi 中查看。

V0.8.1 2024-01-2

  • 增加创建大型群组功能。
  • 删除向大型和小型聊天室发送消息的功能。
  • 批量 添加群组成员 & 移除群组成员 去掉用户列表数量检查。
  • 修改获取 用户 Token 功能的注释说明。

以上更新内容请到 GroupApi & MessageApi & TokenApi 中查看。

V0.8.0 2023-12-21

  • 增加 向聊天室发送定向消息 功能。

以上更新内容请到 MessageApi 中查看。

V0.7.9 2023-11-28

增加查看指定用户是否已加入群组的功能。

以上更新内容请到 GroupApi 中查看。

V0.7.8 2023-11-03

增加指定群主用户发送消息的功能。

以上更新内容请到 MessageApi 中查看。

V0.7.7 2023-10-18

修复下载历史消息文件失败的问题。

V0.7.6 2023-08-30

增加获取多个聊天室详情的功能。

以上更新内容请到 RoomApi 中查看。

V0.7.5 2023-08-24

  • EMProperties 中增加对 ConnectionProvider 的配置项，用于解决 Netty 请求连接问题。
  • 支持修改群组公开或私有属性。 以上更新内容请到 EMProperties 和 GroupApi 中查看。

V0.7.3 2023-07-05

  • 发送聊天室消息增加 chatroom_msg_level 选项。

以上更新内容请到 MessageApi 中查看。

V0.7.2 2023-06-29

  • 增加禁言全体群成员和解除全员禁言功能。
  • 增加群成员自定义属性相关功能。
  • 处理 Rest 服务异常时 Response 返回为空不抛异常的问题。

以上更新内容请到 BlockApi & MetadataApi 中查看。

V0.7.1 2023-06-14

  • 增加 ttl 对获取环信用户 Token 生效的功能。

以上更新内容请到 TokenApi 中查看。

V0.7.0 2023-06-06

  • 增加批量获取群组详情功能。
  • 增加批量禁言/解禁聊天室成员功能。
  • 增加获取群组成员列表包括群主的功能。
  • EMProperties 支持设置 pendingAcquireMaxCount。
  • 修正部分方法使用示例错误的问题。

以上更新内容请到 EMProperties/GroupApi/RoomApi/BlockApi 中查看。

V0.6.9 2023-04-07

  • 增加批量注册用户功能。
  • 增加批量禁言群组成员功能。

以上更新内容请到 UserApi/BlockApi 中查看。

V0.6.8 2023-03-17

更新发送消息与消息撤回方法的内部实现。

V0.6.7 2023-02-07

修复下载附件方法失败的问题。

V0.6.7 2022-12-02

修复注册用户时用户名使用大写字母会失败的问题。

V0.6.6 2022-12-02

修复创建/获取/删除用户方法使用大写字母出现异常的问题。

V0.6.3

  1. 新增 离线推送设置 功能。
  2. 新增 分页获取用户已加入的群组列表 功能。
  3. 新增 批量获取用户属性 功能。
  4. 新增 指定群组 ID 建群 功能，需要联系商务开通。
  5. 修复了一些 Bug。

以上更新内容请到 PushApi/GroupApi/MetadataApi 中查看。

V0.6.0

  1. 新增 聊天室全员禁言/解禁 功能。

  2. 新增 获取聊天室详情返回当前成员人数。

  3. 新增 获取聊天室详情返回成员列表。

  4. 新增 发送消息不返回消息 ID 的方法。

  5. 新增 发送消息可携带 sync_device 字段。

  6. 修复添加群组管理员参数错误无法捕捉异常的问题。

以上更新内容请到 RoomApi/MessageApi 中查看。

V0.5.5

  1. 新增 消息撤回 功能。
  2. 新增 删除单向会话 功能。
  3. 建群时增加群组名称是否需要审核参数。
  4. 获取群成员功能增加是否排序的参数。
  5. 获取群组详情返回群组名称、描述等数据。
  6. 修复调用群组批量移除成员方法移除单个成员时，抛出异常的问题。

以上更新内容请到 GroupApi/MessageApi 中查看。

V0.5.4

新增 设置用户全局禁言/查询单个用户全局禁言剩余时间/查询所有用户全局禁言剩余时间 功能。

以上更新内容请到 MuteApi 中查看。

V0.5.3

  1. 创建群组方法增加 needInviteConfirm(邀请用户加群，受邀用户是否需要确认) 参数。
  2. 创建聊天室方法增加 custom 参数。
  3. 新增聊天室转让方法。

以上更新内容请到 GroupApi/RoomApi 中查看。

V0.5.2

  1. 修改群组信息方法增加 custom 参数。
  2. 新增群组转让方法。

以上更新内容请到 GroupApi 中查看。

环信 IM 文档 Version: 1.0.0 ©️环信