用户属性

更新时间:2022-05-19

用户属性指实时消息互动用户的信息,如用户昵称、头像、邮箱、电话、性别、签名、生日等。

例如,在招聘场景下,利用用户属性功能,可以存储性别、邮箱、用户类型(面试者)、职位类型(web 研发)等。当查看用户信息时,可以直接查询服务器存储的用户属性信息。

注意

为保证用户信息安全,环信即时通讯 IM 仅支持用户本人或 app 管理员设置用户属性。

可以调用以下 REST API 来实现用户属性功能:

主要功能 功能描述
设置用户属性 设置指定的用户的属性。
获取指定用户的所有用户属性 获取指定用户的所有属性。
批量获取用户属性 根据指定的用户名列表和属性列表查询用户属性。
删除用户属性 删除指定用户的所有属性。
获取用户属性总量大小 获取该 app 下所有用户的属性总大小。

要调用环信即时通讯 RESTful API,请确保满足以下要求:

环信即时通讯 IM REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:

Authorization:Bearer ${YourAppToken}

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 推荐使用 app token 的 鉴权方式,详见 使用环信 App Token 鉴权

调用前请了解环信即时通讯 IM 的限制条件,详见 限制条件

设置用户属性

接口描述

用户属性的内容为一个或多个纯文本键值对,默认单一用户的属性总长不得超过 2 KB,默认一个 app 下所有用户的所有属性总长不得超过 10 GB。

请求示例中使用的键是 avatarurlextnickname,你可以根据实际使用场景决定键值。

基本信息

方法:PUT

接入点:https://{host}/{org_name}/{app_name}/metadata/user/{username}

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
username String 必需 用户 ID,长度不可超过 64 个字节长度。不可设置为空。支持以下字符集:
• 26 个小写英文字母 a-z;
• 26 个大写英文字母 A-Z;
• 10 个数字 0-9;
• “_”, “-”, “.”。
注意:
• 不能使用 Email 地址;
• 不能使用 UUID;
• 该参数不区分大小写,因此 Aaaa 为相同用户名;
• 请确保同一个 app 下,username 唯一;
username 用户 ID 是会公开的信息,请不要使用手机号等敏感信息直接注册,需要映射后注册!!!

请求头

参数 类型 是否必需 描述
Content-Type String 必需 内容类型: application/x-www-form-urlencoded
Authorization String 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见 使用环信 App Token 鉴权

请求体

参数 类型
key1 String
key2 String
key3 String
keyN String

请求体的长度限制:

用户属性键值对的 JSON String 长度不能 超过 4 KB。

比如:

requestBody = ‘name=ken&employer=easemob&title=developer’

JSONString = ‘{“name”:“ken”, “employer”:“easemob”, “title”:“developer”}’

这个 JSONString 的总长度不得超过 4 KB。

响应体

参数 描述
timestamp Unix 时间戳,单位为毫秒。
data 用户属性键值对。
duration 请求响应时间, 单位为毫秒。

请求示例

curl -X PUT -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer WMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw12' -d 'avatarurl=http://www.easemob.com/avatar.png&ext=ext&nickname=nickname' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/user1'

响应示例

{
    "timestamp":1620445147011,
    "data":{
        "ext":"ext",
        "nickname":"nickname",
        "avatarurl":"http://www.easemob.com/avatar.png"
    },
    "duration":166
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
403 你尝试设置的用户属性值超过长度限制。该限制可能是对一个用户下的属性总长限制,也可能是对一个 app 下所有用户属性的总长限制。默认单一用户的属性总长不得超过 2 KB,默认一个 app 下所有用户的所有属性总长不得超过 10 GB。
404 表示用户不存在。
409 你尝试修改的用户已经被“别人”修改了。 由于我们对用户属性使用乐观锁处理并发修改问题, 当多个线程同时对同一用户做属性修改时, 只有其中一个线程会修改成功并返回 200, 其他线程都会修改失败并返回 409。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。 如果问题持续存在,请联系我们的技术支持团队。

获取用户属性

接口描述

获取指定用户的所有用户属性键值对。需要在请求时对应填写 {username},需要获取用户属性的用户名。

如果指定的用户或用户属性不存在,返回空数据 {}。

基本信息

方法:GET

接入点:https://{host}/{org_name}/{app_name}/metadata/user/{username}

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
username String 必需 用户 ID。
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。

请求头

参数 类型 是否必需 描述
Content-Type String 必需 内容类型: application/json
Authorization String 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见 使用环信 App Token 鉴权

响应体

参数 描述
timestamp Unix 时间戳,单位为毫秒。
data 用户属性键值对。
duration 请求响应时间,单位为毫秒。

请求示例

curl -X GET 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/user1'

响应示例

{
    "timestamp":1620445147011,
    "data":{
        "ext":"ext",
        "nickname":"nickname",
        "avatarurl":"http://www.easemob.com/avatar.png"
    },
    "duration":166
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
404 用户不存在。
429,503 或者其他 5xx 单位时间内请求过多。请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

批量获取用户属性

接口描述

根据指定的用户名列表和属性列表,查询用户属性。

如果指定的用户或用户属性不存在,返回空数据 {}。 每次最多指定 100 个用户。

基本信息

方法:POST

接入点:https://{host}/{org_name}/{app_name}/metadata/user/get

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
username String 必需 用户 ID。
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。

请求头

参数 类型 是否必需 描述
Content-Type String 必需 内容类型: application/json
Authorization String 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见 使用环信 App Token 鉴权

请求体

参数 类型 是否必需 描述
targets array 必需 用户名列表,最多 100 个用户名。
properties array 必需 属性名列表,查询结果只返回该列表中包含的属性,不在该列表中的属性将被忽略。

响应体

参数 描述
timestamp Unix 时间戳,单位为毫秒。
data 用户属性键值对。
duration 请求响应时间, 单位为毫秒。

请求示例

curl -X POST -H 'Content-Type:  application/json' -d '{
  "properties": [
    "avatarurl",
    "ext",
    "nickname"
  ],
  "targets": [
    "user1",
    "user2",
    "user3"
  ]
}' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/get'

响应示例

{
    "timestamp":1620448826647,
    "data":{
        "user1":{
            "ext":"ext",
            "nickname":"nickname",
            "avatarurl":"http://www.easemob.com/avatar.png"
        },
        "user2":{
            "ext":"ext",
            "nickname":"nickname",
            "avatarurl":"http://www.easemob.com/avatar.png"
        },
        "user3":{
            "ext":"ext",
            "nickname":"nickname",
            "avatarurl":"http://www.easemob.com/avatar.png"
        }
    },
    "duration":3
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
403 指定的用户名数量超过 100。
404 用户不存在。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。 如果问题持续存在,请联系我们的技术支持团队。

获取用户属性总量大小

接口描述

获取该 app 下所有用户的属性数据大小,单位为 byte。

基本信息

方法:GET

接入点:https://{host}/{org_name}/{app_name}/metadata/user/capacity

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。

请求头参数

参数 类型 是否必需 描述
Authorization String 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取的 token 的值。 此处 Token 需要管理员权限,详见 使用环信 App Token 鉴权

响应体参数

参数 描述
timestamp Unix 时间戳,单位为毫秒。
data 该 app 下所有用户属性的数据大小,单位为 byte。
duration 请求响应时间, 单位为毫秒。

请求示例

curl -X GET -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/capacity'

响应示例

{
    "timestamp": 1620447051368,
    "data": 1673,
    "duration": 55
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

删除用户属性

接口描述

删除指定用户的所有属性。如果指定的用户或用户属性不存在(可能已删除),也视为删除成功。

基本信息

方法:DELETE

接入点:https://{host}/{org_name}/{app_name}/metadata/user/{username}

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
username String 必需 用户 ID。

请求头

参数 类型 是否必需 描述
Authorization String 必需 Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。详见 使用环信 App Token 鉴权

响应体

参数 描述
timestamp Unix 时间戳,单位为毫秒。
data Boolean, 是否删除成功。
duration 请求响应时间, 单位为毫秒。

请求示例

curl -X DELETE -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/user1'

响应示例

{
    "timestamp": 1616573382270,
    "duration": 10,
    "data": true
}

响应码

状态码 描述
200 data 为 true 表示删除用户属性成功,注意删除不存在用户也视作成功。
400 请求参数错误,请根据返回提示检查。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429,503或者其他5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。