网易云信即时通讯 NIM QChat Web SDK 的QChatServerServiceInterface接口提供搜索圈组的服务器和服务器成员方法，QChatChannelServiceInterface接口提供搜索频道的方法。SDK 还支持配置搜索结果的排序规则，如搜索出的服务器列表可按时间和人数等维度排序，也可自定义排序。

在开通圈组功能后，圈组搜索相关能力还需再单独开通才可调用，您可通过云信官网提供的联系方式咨询商务经理开通。

应用场景

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

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

技术原理

搜索数据来源

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

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

与服务器信息的关联逻辑

定义服务器的serverInfo结构体，包含searchEnable和searchType。

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

前提条件

在进行圈组搜索功能集成前，请确保您已：

• 开通圈组搜索功能。如尚未开通，您可通过云信官网首页提供的在线咨询、微信或电话等方式联系商务经理开通该功能。
• 创建圈组服务器。
• 创建频道。

搜索服务器

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

入参	必传	类型	说明
keyword	是	string	搜索关键字
searchType	是	TSearchType	搜索场景： square-广场，即全局搜索服务器 person-搜索个人已加入的服务器
startTime	否	number	查询时间范围的开始时间
endTime	否	number	查询时间范围的结束时间，必须比开始时间晚
order	否	TQChatSearchOrder	排序规则：ASC-升序，DESC-倒序
limit	否	number	返回结果的记录数，最大和默认都是 100
serverType	否	number	自定义，搜索的服务器类型
sort	否	TSortType	服务器的排序条件，默认为按创建时间倒序排序，即最新创建的服务器排在最前 如需实现搜索结果自定义排序，请参照下文的搜索结果自定义排序中的说明进行配置
cursor	否	string	游标, 搜索的起始位置

全局搜索服务器

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

• 示例代码

  const qchat = new QChat({...})
  qchat.qchatServer.serverSearchByPage({
      keyword:"",
      order:"DESC",
      searchType:"square"
  })
  

• API 调用时序示例

  全局搜索仅能搜索到“允许被搜索”的服务器。如下时序图中创建的服务器均为可被搜索的服务器。

搜索已加入的服务器

• 示例代码

  const qchat = new QChat({...})
  qchat.qchatServer.serverSearchByPage({
      keyword:"",
      order:"DESC",
      searchType:"person"
  })
  

• API 调用时序示例

  

搜索服务器成员

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

入参说明

参数名	必选	类型	说明
keyword	是	string	关键字
serverId	是	string	服务器 ID
limit	是	number	查询条数，最大和默认都为 100

示例代码

const qchat = new QChat({...})
qchat.qchatServer.serverMemberSearchByPage({
    serverId:"",
    keyword:""
}})

API 调用时序示例

搜索频道

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

入参说明

参数名	必选	类型	说明
keyword	是	string	关键字
startTime	否	number	查询时间范围的开始时间
endTime	否	number	查询时间范围的结束时间，必须比开始时间晚
order	否	TQChatSearchOrder	排序规则：ASC-升序，DESC-倒序
limit	否	number	返回结果的记录数，最大和默认都是 100
serverId	否	string	不填时查询所有服务器，填写时查询指定服务器
sort	否	TSortType	服务器的排序条件，默认为按创建时间倒序排序，即最新创建的频道排在最前 如需实现搜索结果自定义排序，请参照下文的搜索结果自定义排序中的说明进行配置
cursor	否	string	游标, 搜索的起始位置

示例代码

const qchat = new QChat({...})
qchat.qchatChannel.getChannelSearchByPage({
    serverId:"",
    keyword:"",
    order:"ASC"
}})

API 调用时序示例

搜索结果自定义排序

定义圈组服务器的ServerInfo结构体包含服务器的自定义排序权重（reorderWeight），默认为 0。同样的，定义频道的ChannelInfo结构体包含频道的自定义排序权重（reorderWeight），默认为 0。自定义排序权重值，目前仅支持通过服务器端 API 修改。

服务器自定义排序

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

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

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

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

   结果：

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

频道自定义排序

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

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

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

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

   结果：

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

API 参考

API	说明
serverSearchByPage	分页搜索服务器
serverMemberSearchByPage	搜索服务器成员
getChannelSearchByPage	分页搜索频道
qchat/batchUpdateServerReorderWeight.action	修改服务器的自定义排序权重值
qchat/batchUpdateChannelReorderWeight.action	修改频道的自定义排序权重值