即时通信 IM
开发与运维产品文档捉虫活动邀您参加！> HOT
文档中心>即时通信 IM>服务端 API>REST API>云端搜索>用户搜索

用户搜索

最近更新时间：2024-12-25 10:51:52

我的收藏

本页目录：

功能说明

可以通过本接口，搜索模糊匹配的用户名称（UserNick）或者精确匹配的 UserID。
使用前提：请先前往购买页 购买云端搜索 插件并在控制台插件市场 > 云端搜索开启用户搜索开关。

接口调用说明

请求 URL 示例

https://xxxxxx/v4/user_search/search?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明，更多参数详情请参考 REST API 简介。
参数
说明
xxxxxx
当前仅支持中国站，SDKAppID 所在国家/地区对应的专属域名：
中国：console.tim.qq.com
新加坡：adminapisgp.im.qcloud.com
其他站点暂不支持。
v4/user_search/search
用户搜索接口。
sdkappid
创建应用时即时通信 IM 控制台分配的 SDKAppID。
identifier
必须为 App 管理员账号，更多详情请参见 App 管理员。
usersig
App 管理员账号生成的签名，具体操作请参见 生成 UserSig。
random
请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype
请求格式固定值为json。

最高调用频率

2次/秒。

请求包示例

{
    "Count": 1,
    "UserGenderType":"Gender_Type_Female",
    "KeywordMatchType": 1,
    "UserBirthStart":0,
    "UserBirthEnd":1730774469, 
    "Keywords": [
        "abcd"
    ],
    "Cursor": ""
}


请求包字段说明

字段
类型
属性
说明
UserGenderType
String
选填
过滤性别，为空表示未指定。
Gender_Type_Female:女
Gender_Type_Male:男
UserBirthStart
Integer
选填
过滤起始出生日期，该字段意义是用户决定，我们只保证为整型。
UserBirthEnd
Integer
选填
过滤结束出生日期，该字段要比 user_birth_start 大。
KeywordMatchType
Integer
选填
逻辑运算符。
1：and
0：or
默认为 or。
Keywords
Array
必填
模糊搜索的 Keywords。
Count
Integer
必填
一次请求最大记录数，最大100条，超过100条按100处理。
Cursor
String
选填
续拉参数，上个请求的 Response 中带回，首次请求为空。

应答包体示例

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "IsFinish": false,
    "TotalCount": 1,
    "Users": [
        {
            "UserID": "abcd",
            "ProfileItems": [
                {
                    "Tag": "Tag_Profile_IM_Nick",
                    "StrValue": "   abcddhdj"
                },
                {
                    "Tag": "Tag_Profile_IM_Gender",
                    "StrValue": "Gender_Type_Female"
                },
                {
                    "Tag": "Tag_Profile_IM_BirthDay",
                    "IntValue": 21110815
                },
                {
                    "Tag": "Tag_Profile_IM_Location",
                    "StrValue": "未发现哈哈�"
                },
                {
                    "Tag": "Tag_Profile_IM_SelfSignature",
                    "StrValue": "暂无就觉得看看对酒当歌大姐大抗打击赶大集到啦"
                },
                {
                    "Tag": "Tag_Profile_IM_Image",
                    "StrValue": "https://picsum.photos/id/880/200/200"
                },
                {
                    "Tag": "Tag_Profile_IM_AdminForbidType",
                    "StrValue": "AdminForbid_Type_None"
                }
            ]
        }
    ],
    "Cursor": "nvWNvg7lJePQgCQGxYNogjo2PbnxaX1PlRHWSDCCSyA"
}

应答包字段说明

字段
类型
说明
ActionStatus
String
请求处理的结果，OK 表示处理成功，FAIL 表示失败。
ErrorCode
Integer
错误码，0表示成功，非0表示失败。
ErrorInfo
String
错误信息。
IsFinish
Bool
搜索是否结束。
TotalCount
Integer
命中的搜索结果个数。
Users
Array
命中的用户数。
UserID
String
命中的用户 UserID。
ProfileItems
Array
命中的用户所有标准资料字段。
Tag
String
命中的用户资料字段名。
IntValue
Integer
命中的用户资料字段如果为整形，取该值。
StrValue
String
命中的用户资料字段如果为字符串，取该值。
Cursor
Integer
续拉参数，下个请求的Response中带回。

错误码说明

除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。实际的错误码、错误信息是通过应答包体中的 ResultCode、ResultInfo、ErrorCode 以及 ErrorInfo 来表示的。
公共错误码（60000到79999）请参见 错误码。
本 API 私有错误码如下：
错误码
描述
27003
请求参数异常，请根据错误提示排查原因。
27004
服务内部异常，重试仍有问题可以通过工单联系我们。
60018
请求过于频繁，请稍后重试。
60020
云端搜索套餐包过期或者响应搜索场景没有开启，请检查后重试。
中国站
文档活动
message-icon联系我们
目录