IM 即时通讯
Windows/macOS
开发指南

搜索服务器和频道

更新时间: 2023/06/29 14:52:29

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

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

前提条件

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

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

应用场景

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

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

技术原理

搜索数据来源

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

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

圈组搜索原理.png

与服务器的关联逻辑

定义服务器的NIMQChatServerInfo,包含searchableserver_type

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

前提条件

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

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

搜索服务器

调用ServerSearchByPage方法可搜索服务器,返回在start_timeend_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方法搜索服务器。调用时除了必传的入参keywordsearch_Typeorder外,还需传入sort,且将其设置为kNIMQChatServerSearchSortCustom

      结果

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

    频道自定义排序

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

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

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

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

      结果

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

    API 参考

    API
    说明
    ServerSearchByPage 分页搜索服务器
    ServerMemberSearch 搜索服务器成员
    ChannelSearchByPage 分页搜索频道
    ChannelMemberSearch 搜索频道成员
    qchat/batchUpdateServerReorderWeight.action 修改服务器的自定义排序权重值
    qchat/batchUpdateChannelReorderWeight.action 修改频道的自定义排序权重值
    此文档是否对你有帮助?
    有帮助
    去反馈
    • 前提条件
    • 应用场景
    • 技术原理
    • 搜索数据来源
    • 与服务器的关联逻辑
    • 前提条件
    • 搜索服务器
    • 入参说明
    • 示例代码
    • 搜索服务器成员
    • 入参说明
    • 示例代码
    • 搜索频道
    • 入参说明
    • 示例代码
    • 搜索频道成员
    • 入参说明
    • 示例代码
    • 搜索结果自定义排序
    • 服务器自定义排序
    • 频道自定义排序
    • API 参考