网易云信即时通讯 NIM SDK 的QChatServerService接口提供搜索圈组的服务器和服务器成员的方法，QChatChannelService接口提供搜索频道和频道成员的方法。

SDK 还支持配置搜索结果的排序规则，如搜索出的服务器列表可按时间和人数等维度排序，也可自定义排序。

应用场景

圈组的搜索能力和配套的搜索结果排序能力，可满足您的应用的特定运营需求，如：

• 通过按人数排序，将热门社区（对应圈组服务器）展示在用户搜索结果的前列，方便用户加入热门社区。
• 通过自定义排序，将广告位性质的话题（对应频道）展示在用户搜索结果的前列，增加流量引入。

技术原理

搜索数据来源

下图左侧所示事件发生后，将触发相关消息通过消息队列（Message Queue）通知云信搜索服务器，搜索服务器把相关的事件数据保存或更新到 Elasticsearch。

由于整个数据传送过程都是通过消息队列生产消费，且 Elasticsearch 的数据每秒刷新一次，所以整体的搜索数据存在一定的延迟（正常 3 秒内）。

与服务器的关联逻辑

服务器创建、更新、查询等方法（包括createServer和updateServer），入参包含searchEnable和searchType。

参数	说明
searchEnable	服务器是否允许被搜索，true-允许，false-不允许，默认允许
searchType	服务器搜索类型，客户自定义，大于等于 0 的整数。 0 代表无类型

前提条件

开始搜索功能集成前，请确保您已：

• 已开通圈组搜索功能。圈组搜索功能需要在开通圈组功能的基础上额外开通后才能使用。
• 创建圈组服务器。
• 创建频道。

实现方法

搜索服务器

调用 searchServerByPage方法可搜索服务器，返回在startTime和endTime之间的时间段内创建并与keyword匹配的服务器。

该方法的入参如下表所示：

参数	必传	类型	说明
keyword	是	String	目标检索服务器名称的关键字，最大长度 100 字符，支持模糊搜索。关键字必须为连续字符串，? 和 * 会被忽略。 例子：假设服务器的名称为“网易云信专属服务器”，用户使用如下三个关键字进行搜索，keyword1=“网易云信”，keyword2=“专属服”，keyword3=“网专属”,keyword4=“网易 云信”，那么只有 keyword1 和 keyword2 能搜索到该服务器
asc	是	boolean	true-升序，false-降序
searchType	是	QChatSearchServerTypeEnum	配置搜索类型： 传 Square 为全局搜索服务器 传 Personal 为搜索已加入的服务器
startTime	否	Long	查询时间范围的开始时间
endTime	否	Long	查询时间范围的结束时间，必须比开始时间晚
limit	否	Integer	每页结果条数，最大和默认都是 100
serverTypes	否	List	服务器类型，对应创建服务器时传入的searchType
sort	否	QChatServerSearchSortEnum	服务器的排序条件，默认为按创建时间倒序排序，即最新创建的服务器排在最前 如需实现搜索结果自定义排序，请参照下文的搜索结果自定义排序中的说明进行配置
cursor	否	String	游标, 搜索的起始位置

全局搜索服务器

全局搜索集成圈组的应用内的所有服务器，包括已加入的和未加入的服务器。

全局搜索仅能搜索到“允许被搜索”的服务器。

• 示例代码

  QChatSearchServerByPageParam param = new QChatSearchServerByPageParam("keyword", true, QChatSearchServerTypeEnum.Square);
  NIMClient.getService(QChatServerService.class).searchServerByPage(param).setCallback(new RequestCallback<QChatSearchServerByPageResult>() {
      @Override
      public void onSuccess(QChatSearchServerByPageResult result) {
          //成功
      }
  
      @Override
      public void onFailed(int code) {
          // 失败
      }
  
      @Override
      public void onException(Throwable exception) {
          // 出现异常
      }
  });
  

搜索已加入的服务器

• 示例代码

  QChatSearchServerByPageParam param = new QChatSearchServerByPageParam("keyword", true, QChatSearchServerTypeEnum.Personal);
  NIMClient.getService(QChatServerService.class).searchServerByPage(param).setCallback(new RequestCallback<QChatSearchServerByPageResult>() {
      @Override
      public void onSuccess(QChatSearchServerByPageResult result) {
          //成功
      }
  
      @Override
      public void onFailed(int code) {
          // 失败
      }
  
      @Override
      public void onException(Throwable exception) {
          // 出现异常
      }
  });
  

搜索服务器成员

调用 searchServerMemberByPage 方法搜索服务器成员。

参数	必传	类型	说明
keyword	是	String	目标成员的昵称或 IM 账号的关键字，最大 100 个字符，支持模糊搜索，模糊搜索的限制同上文提及的搜索服务器的 keyword
serverId	是	long	服务器 ID
limit	否	Integer	每页结果条数，最大和默认都是 100

示例代码

QChatSearchServerMemberByPageParam param = new QChatSearchServerMemberByPageParam("keyword", 123456L);
NIMClient.getService(QChatServerService.class).searchServerMemberByPage(param).setCallback(new RequestCallback<QChatSearchServerMemberByPageResult>() {
    @Override
    public void onSuccess(QChatSearchServerMemberByPageResult result) {
        //成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
        // 出现异常
    }
});

搜索频道

调用 searchChannelByPage 方法搜索对当前用户可见的频道（即当前用户未被加入黑名单的公开频道和已被加入白名单的私密频道）。

参数	必传	类型	说明
keyword	是	String	目标检索的频道名称的关键字，最大长度 100 字符，支持模糊搜索，模糊搜索的限制同上文提及的搜索服务器的 keyword
asc	是	boolean	排序规则 1： ASC 2： DESC
startTime	否	Long	查询时间范围的开始时间
endTime	否	Long	查询时间范围的结束时间，要求比开始时间大
limit	否	Integer	每页结果条数，最大和默认都是 100
serverId	否	Long	不填时查询所有服务器下的频道，填写时查询指定服务器下的频道
sort	否	QChatChannelSearchSortEnum	频道的排序条件，默认为按创建时间倒序排序，即最新创建的频道排在最前 如需实现搜索结果自定义排序，请参照下文的搜索结果自定义排序中的说明进行配置
cursor	否	string	游标, 搜索的起始位置

示例代码

QChatSearchChannelByPageParam param = new QChatSearchChannelByPageParam("keyword", true);
param.setServerId(123456L);
NIMClient.getService(QChatChannelService.class).searchChannelByPage(param).setCallback(new RequestCallback<QChatSearchChannelByPageResult>() {
    @Override
    public void onSuccess(QChatSearchChannelByPageResult result) {
        //成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
        // 出现异常
    }
});

搜索频道成员

调用 searchChannelMembers 方法搜索频道成员。

参数	必传	类型	说明
keyword	是	String	目标成员的昵称或 IM 账号的关键字，最大 100 个字符，支持模糊搜索，模糊搜索的限制同上文提及的搜索服务器的 keyword
serverId	是	long	服务器 ID
channelId	是	long	频道 ID
limit	否	Integer	检索返回的最大记录数，最大和默认都是 100

示例代码

QChatSearchChannelMembersParam param = new QChatSearchChannelMembersParam(123L, 456L, "keyword");
NIMClient.getService(QChatChannelService.class).searchChannelMembers(param).setCallback(
		new RequestCallback<QChatSearchChannelMembersResult>() {
			@Override
			public void onSuccess(QChatSearchChannelMembersResult result) {
				// 成功
			}

			@Override
			public void onFailed(int code) {
				// 失败
			}

			@Override
			public void onException(Throwable exception) {
				// 出现异常
			}
		});

搜索结果自定义排序

• 创建服务器成功后返回的QChatCreateServerResult中的QChatServer包含服务器的自定义排序权重信息（ReorderWeight），默认为 0。
• 创建频道成功后返回的QChatCreateChannelResult中的QChatChannel包含频道的自定义排序权重信息（ReorderWeight），默认为 0。自定义排序权重值，目前仅支持通过服务器端 API 修改。
• 创建频道分组成功后返回的QChatCreateChannelCategoryResult中的QChatChannelCategory包含频道分组的自定义排序权重信息（ReorderWeight），默认为 0。自定义排序权重值，目前仅支持通过服务器端 API 修改。

服务器自定义排序

实现服务器搜索结果自定义排序的流程如下：

1. 调用服务端 API （qchat/batchUpdateServerReorderWeight.action）修改服务器的自定义排序权重值。

   调用该 API 单次可修改权重的服务器的数量上限默认为 10。如需调整该上限，请通过云信官网首页的在线聊天、微信和电话等联系方式咨询商务经理。

2. 调用searchServerByPage方法搜索服务器。调用时除了必传的入参keyword、searchType和asc外，还需传入sort，且将其设置为ReorderWeight。

   结果：

   • 如asc为默认倒序，则匹配的服务器列表以权重值倒序排列，相同权重的服务器按serverId倒序排列。
   • 如asc为正序，则按权重值正序排序，相同权重的按serverId倒序排列。

频道自定义排序

实现频道搜索结果自定义排序的流程如下：

1. 调用服务端 API （qchat/batchUpdateChannelReorderWeight.action）修改频道的自定义排序权重默认值。

   调用该 API 单次可修改权重值的频道的数量上限默认为 10。如需调整该上限，请通过云信官网首页的在线聊天、微信和电话等联系方式咨询商务经理。

2. 调用searchChannelByPage方法搜索频道。调用时除了必传的入参keyword 和asc外，还需传入sort，且将其设置为ReorderWeight。

   结果：

   • 如asc为默认倒序，则匹配的频道列表以权重值倒序排列，相同权重的频道按channelId倒序排列。
   • 如asc为正序，则按权重值正序排序，相同权重的按channelId倒序排列。

频道分组自定义排序

实现频道分组搜索结果自定义排序的流程如下：

1. 调用服务端 API （qchat/updateChannelCategory.action）修改频道分组的自定义排序权重默认值。

2. 调用 QChatChannelService.getChannelCategoriesByPage 方法查询频道分组。调用时将入参 sortType 设置为 按自定义权重排序，并传入 cursor 实现分页。

   示例代码如下：

   //服务器id
   long serverId = 12345678L;
   //查询锚点时间戳，传0取当前时间戳
   long timeTag = 0L;
   //分页标记，第一页不传，翻下一页传接口返回的cursor
   String cursor = null;
   //查询数量
   int limit = 100;
   //查询排序类型，默认CreateTime
   QChatChannelCategorySearchSortEnum sortType = QChatChannelCategorySearchSortEnum.ReorderWeight;
   QChatGetChannelCategoriesByPageParam param =
       new QChatGetChannelCategoriesByPageParam.Builder()
           .serverId(serverId)
           .timeTag(timeTag)
           .sortType(sortType)
           .cursor(cursor)
           .limit(limit)
           .build();
   NIMClient.getService(QChatChannelService.class).getChannelCategoriesByPage(param).setCallback(new RequestCallback<QChatGetChannelCategoriesByPageResult>() {
       @Override
       public void onSuccess(QChatGetChannelCategoriesByPageResult result) {
           //查询成功
           //查询到的频道分组列表
           List<QChatChannelCategory> channels = result.getCategories();
           //下一页查询标记
           String nextCursor = result.getCursor();
   
       }
   
       @Override
       public void onFailed(int code) {
           //查询失败
       }
   
       @Override
       public void onException(Throwable exception) {
           //查询异常
       }
   });