用户属性
更新时间:2022-05-19
功能描述
用户属性指实时消息互动用户的信息,如用户昵称、头像、邮箱、电话、性别、签名、生日等。
例如,在招聘场景下,利用用户属性功能,可以存储性别、邮箱、用户类型(面试者)、职位类型(web 研发)等。当查看用户信息时,可以直接查询服务器存储的用户属性信息。
注意
为保证用户信息安全,环信即时通讯 IM 仅支持用户本人或 app 管理员设置用户属性。
可以调用以下 REST API 来实现用户属性功能:
主要功能 | 功能描述 |
---|---|
设置用户属性 | 设置指定的用户的属性。 |
获取指定用户的所有用户属性 | 获取指定用户的所有属性。 |
批量获取用户属性 | 根据指定的用户名列表和属性列表查询用户属性。 |
删除用户属性 | 删除指定用户的所有属性。 |
获取用户属性总量大小 | 获取该 app 下所有用户的属性总大小。 |
前提条件
要调用环信即时通讯 RESTful API,请确保满足以下要求:
- 已在环信即时通讯控制台 开通配置环信即时通讯 IM 服务。
- 已从服务端获取 app token,详见 使用环信 app token 鉴权。
认证方式
环信即时通讯 IM REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:
Authorization:Bearer ${YourAppToken}
为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 推荐使用 app token 的 鉴权方式,详见 使用环信 App Token 鉴权。
实现方法
调用前请了解环信即时通讯 IM 的限制条件,详见 限制条件。
设置用户属性
接口描述
用户属性的内容为一个或多个纯文本键值对,默认单一用户的属性总长不得超过 2 KB,默认一个 app 下所有用户的所有属性总长不得超过 10 GB。
请求示例中使用的键是 avatarurl
、ext
、nickname
,你可以根据实际使用场景决定键值。
基本信息
方法: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; • 该参数不区分大小写,因此 Aa 和 aa 为相同用户名; • 请确保同一个 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 错误。如果问题持续存在,请联系我们的技术支持团队。 |