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

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

在开通圈组功能后，圈组搜索相关能力还需再单独开通才可调用。

可在云信控制台开通该功能

在云信控制台选择应用，进入IM 免费版/专业版 > 功能权限开通 > 拓展配置 > 圈组 > 搜索功能即可配置。

应用场景

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

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

技术原理

搜索数据来源

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

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

与服务器的关联逻辑

定义服务器的NIMQChatServerInfo，包含searchable和server_type。

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

前提条件

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

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

搜索服务器

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

入参说明

入参	必传	类型	说明
keyword	是	std::string	目标检索服务器名称的关键字，最大长度 100 字符，支持模糊搜索。关键字必须为连续字符串，? 和 * 会被忽略。 例子：假设服务器的名称为“网易云信专属服务器”，用户使用如下三个关键字进行搜索，keyword1=“网易云信”，keyword2=“专属服”，keyword3=“网专属”,keyword4=“网易 云信”，那么只有 keyword1 和 keyword2 能搜索到该服务器
order	是	NIMQChatSearchOrder	排序规则，倒序或正序，默认倒序
search_type	是	NIMQChatServerSearchType	搜索类型，kNIMQChatServerSearchTypeSquare-广场搜索，即全局搜索集成圈组的应用的所有可被搜索的服务器 kNIMQChatServerSearchTypePersonal-搜索已加入的服务器
start_time	否	uint64_t	起始时间
end_time	否	uint64_t	结束时间
server_types	否	uint32_t	搜索的服务器类型, 为空表示搜索所有类型
limit	否	uint32_t	每页数据条数，最大和默认都是 100
sort	否	NIMQChatServerSearchSort	服务器的排序条件，默认为按创建时间倒序排序，即最新创建的服务器排在最前 如需实现搜索结果自定义排序，请参照下文的搜索结果自定义排序中的说明进行配置
cursor	否	string	游标, 搜索的起始位置

示例代码

// search server
QChatServerSearchPageParam param;
param.keyword = "keyword";
param.start_time = 0;
param.end_time = 0; // no time range limit
param.limit = 20
param.order = kNIMQChatSearchOrderDesc;
param.server_types = {}; // empty means all server types
param.search_type = kNIMQChatServerSearchTypeSquare; // search in squre or search in servers which you belong to
param.cb = [this](const QChatServerSearchPageResp& resp) {
    if (resp.res_code != NIMResCode::kNIMResSuccess) {
        // error handling
        return;
    }
    // process response
    // ...
};
Server::ServerSearchByPage(param);

搜索服务器成员

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

入参说明

参数名	必选	类型	说明
keyword	是	std::string	目标成员的昵称或 IM 账号的关键字，最大 100 个字符，支持模糊搜索，模糊搜索的限制同上文提及的搜索服务器的 keyword
server_id	是	uint64_t	服务器 ID
limit	否	uint32_t	检索返回的最大记录数，最大和默认都是 100

示例代码

// search server members
QChatServerMemberSearchParam param;
param.server_id = 123456;
param.keyword = "keyword";
param.limit = 20;
param.cb = [this](const QChatServerMemberSearchResp& resp) {
    if (resp.res_code != NIMResCode::kNIMResSuccess) {
        // error handling
        return;
    }
    // process response
    // ...
};
Server::ServerMemberSearch(param);

搜索频道

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

入参说明

参数名	必传	类型	说明
keyword	是	std::string	目标频道名称的关键字，最大 100 个字符，支持模糊搜索，模糊搜索的限制同上文提及的搜索服务器的 keyword
order	是	NIMQChatSearchOrder	排序规则
server_id	否	uint64_t	服务器ID，不填则查询所有服务器的频道
start_time	否	uint64_t	起始时间
end_time	否	uint64_t	结束时间
limit	否	uint32_t	每页数据条数，最大和默认都是 100
sort	否	NIMQChatChannelSearchSort	搜索出的频道的排序条件，默认为按创建时间倒序排序，即最新创建的频道排在最前 如需实现搜索结果自定义排序，请参照下文的搜索结果自定义排序中的说明进行配置
cursor	否	string	游标, 搜索的起始位置

示例代码

// search channel
QChatChannelSearchPageParam param;
param.server_id = 123456; // set it to 0 if you want to seach in all servers which you belong to
param.keyword = "keyword";
param.start_time = 0;
param.end_time = 0; // no time range limit
param.limit = 20;
param.order = kNIMQChatSearchOrderDesc;
param.cb = [this](const QChatChannelSearchPageResp& resp) {
    if (resp.res_code != NIMResCode::kNIMResSuccess) {
        // error handling
        return;
    }
    // process response
    // ...
};
Channel::ChannelSearchByPage(param);

搜索频道成员

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

入参说明

参数名	必选	类型	说明
keyword	是	std::string	目标成员的昵称或 IM 账号的关键字，最大 100 个字符，支持模糊搜索，模糊搜索的限制同上文提及的搜索服务器的 keyword
server_id	是	uint64_t	服务器 ID
channel_id	是	uint64_t	频道 ID
limit	否	uint32_t	检索返回的最大记录数，最大和默认都是 100

示例代码

// search channel members
QChatChannelMemberSearchParam param;
param.server_id = 123456;
param.channel_id = 123456;
param.keyword = "keyword";
param.limit = 20;
param.cb = [this](const QChatChannelMemberSearchResp& resp) {
    if (resp.res_code != NIMResCode::kNIMResSuccess) {
        // error handling
        return;
    }
    // process response
    // ...
};
Channel::ChannelMemberSearch(param);

搜索结果自定义排序

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

服务器自定义排序

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

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

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

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

   结果：

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

频道自定义排序

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

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

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

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

   结果：

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

API 参考

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